Compare commits
22 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Alex Newman
|
35b7aab174 | ||
|
Alex Newman
|
2601215c91 | ||
|
Alex Newman
|
4ebf0cad6b | ||
|
Alex Newman
|
98d959112c | ||
|
Alex Newman
|
d01c2afaa6 | ||
|
Alex Newman
|
8ebcb55b0d | ||
|
Alex Newman
|
97807494fd | ||
|
Alex Newman
|
c4eb2e2dc9 | ||
|
Alex Newman
|
f0c3bf18b0 | ||
|
Alex Newman
|
3eaae66bc4 | ||
|
Alex Newman
|
27d1cd405f | ||
|
Alex Newman
|
267965a065 | ||
|
Alex Newman
|
181aca0215 | ||
|
Alex Newman
|
b6eef0145f | ||
|
Alex Newman
|
a1bc421fea | ||
|
Alex Newman
|
502b3894d7 | ||
|
Alex Newman
|
8e9005d9c3 | ||
|
Alex Newman
|
7978f84f6c | ||
|
Alex Newman
|
f1f578c6fb | ||
|
Alex Newman
|
aae7de8e05 | ||
|
thedotmack
|
4da61a77c7 | ||
|
thedotmack
|
4fbb25e385 |
+5
-11
@@ -1,13 +1,7 @@
|
||||
# Binaries (distributed via GitHub releases)
|
||||
*.exe
|
||||
*.app
|
||||
claude-mem
|
||||
claude-mem-*
|
||||
|
||||
# Temporary files
|
||||
*.tmp
|
||||
node_modules/
|
||||
*.log
|
||||
.DS_Store
|
||||
|
||||
# Node modules (if any)
|
||||
node_modules/
|
||||
.env
|
||||
.env.local
|
||||
*.tmp
|
||||
*.temp
|
||||
|
||||
+105
@@ -0,0 +1,105 @@
|
||||
# Changelog
|
||||
|
||||
All notable changes to this project will be documented in this file.
|
||||
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
|
||||
|
||||
|
||||
## [3.6.10] - 2025-09-16
|
||||
|
||||
### Added
|
||||
- Claude Code statusline integration for real-time memory status
|
||||
- MCP memory tools server providing compress, stats, search, and overview commands
|
||||
- Concept documentation explaining memory compression and context loading
|
||||
|
||||
### Fixed
|
||||
- Corrected integration architecture to use hooks instead of MCP SDK
|
||||
|
||||
|
||||
## [3.6.9] - 2025-09-14
|
||||
|
||||
### Added
|
||||
- Display current date and time at the top of session-start hook output for better temporal context
|
||||
|
||||
### Changed
|
||||
- Enhanced session-start hook formatting with emoji icons and separator lines for improved readability
|
||||
|
||||
|
||||
## [3.6.8] - 2025-09-14
|
||||
|
||||
### Fixed
|
||||
- Fixed publish command failing when no version-related memories exist for changelog generation
|
||||
|
||||
|
||||
## [3.6.6] - 2025-09-14
|
||||
|
||||
### Fixed
|
||||
- Resolved compaction errors when processing large conversation histories by reducing chunk size limits to stay within Claude's context window
|
||||
|
||||
|
||||
## [3.6.5] - 2025-09-14
|
||||
|
||||
### Changed
|
||||
- Session groups now display in chronological order (most recent first)
|
||||
|
||||
### Fixed
|
||||
- Improved CLI path detection for cross-platform compatibility
|
||||
|
||||
|
||||
## [3.6.4] - 2025-09-13
|
||||
|
||||
### Changed
|
||||
- Update save documentation to include allowed-tools and description metadata fields
|
||||
|
||||
### Removed
|
||||
- Remove deprecated markdown to JSONL migration script
|
||||
|
||||
|
||||
## [3.6.3] - 2025-09-11
|
||||
|
||||
### Changed
|
||||
- Updated changelog generation prompts to use date strings in query text for temporal filtering
|
||||
|
||||
### Fixed
|
||||
- Resolved changelog timestamp filtering by using semantic search instead of metadata queries, enabling proper date-based searches
|
||||
- Corrected install.ts search instructions to remove misleading metadata filtering guidance that caused 'Error finding id' errors
|
||||
|
||||
|
||||
## [3.6.2] - 2025-09-10
|
||||
|
||||
### Added
|
||||
- Visual feedback to changelog command showing current version, next version, and number of overviews being processed
|
||||
- Generate changelog for specific versions using `--generate` flag with npm publish time boundaries
|
||||
- Introduce 'Who Wants To Be a Memoryonaire?' trivia game that generates personalized questions from your stored memories
|
||||
- Add interactive terminal UI with lifelines (50:50, Phone-a-Friend, Audience Poll) and cross-platform audio support
|
||||
- Implement permanent question caching with --regenerate flag for instant game loading
|
||||
- Enable hybrid vector search to discover related memory chains during question generation
|
||||
|
||||
### Changed
|
||||
- Changelog regeneration automatically removes old entries from JSONL file when using `--generate` or `--historical` flags
|
||||
- Switch to direct JSONL file loading for instant memory access without API calls
|
||||
- Optimize AI generation with faster 'sonnet' model for improved performance
|
||||
- Reduce memory query limit from 100 to 50 to prevent token overflow
|
||||
|
||||
### Fixed
|
||||
- Changelog command now uses npm publish timestamps exclusively for accurate version time ranges
|
||||
- Resolved timestamp filtering issues with Chroma database by leveraging semantic search with embedded dates
|
||||
- Resolve game hanging at startup due to confirmation loop
|
||||
- Fix memory integration bypass that prevented questions from using actual stored memories
|
||||
- Consolidate 500+ lines of duplicate code for better maintainability
|
||||
|
||||
|
||||
## [3.6.1] - 2025-09-10
|
||||
|
||||
### Changed
|
||||
- Refactored pre-compact hook to work independently without status line updates
|
||||
|
||||
### Removed
|
||||
- Removed status line integration and ccstatusline configuration support
|
||||
|
||||
|
||||
## [3.5.5] - 2025-09-10
|
||||
|
||||
### Changed
|
||||
- Standardized GitHub release naming to lowercase 'claude-mem vX.X.X' format for consistent branding
|
||||
|
||||
@@ -1,43 +1,632 @@
|
||||
# Claude Mem License
|
||||
|
||||
Copyright (c) 2024 Alex Newman (@thedotmack)
|
||||
|
||||
## Binary Distribution License
|
||||
GNU AFFERO GENERAL PUBLIC LICENSE
|
||||
Version 3, 19 November 2007
|
||||
|
||||
The compiled binaries (claude-mem, claude-mem.exe, etc.) are provided free of charge for personal and commercial use under the following terms:
|
||||
Copyright (C) 2025 Alex Newman (@thedotmack). All rights reserved.
|
||||
|
||||
1. **USE**: You may use the binaries for any purpose.
|
||||
2. **DISTRIBUTION**: You may redistribute the unmodified binaries.
|
||||
3. **NO REVERSE ENGINEERING**: You may not decompile, disassemble, or reverse engineer the binaries.
|
||||
4. **NO MODIFICATION**: You may not modify the binary files.
|
||||
5. **NO WARRANTY**: The software is provided "as is" without warranty of any kind.
|
||||
This program is free software: you can redistribute it and/or modify
|
||||
it under the terms of the GNU Affero General Public License as published by
|
||||
the Free Software Foundation, either version 3 of the License, or
|
||||
(at your option) any later version.
|
||||
|
||||
## Hook Files License (MIT)
|
||||
This program is distributed in the hope that it will be useful,
|
||||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
GNU Affero General Public License for more details.
|
||||
|
||||
The hook files in the `/hooks` directory are licensed under the MIT License:
|
||||
You should have received a copy of the GNU Affero General Public License
|
||||
along with this program. If not, see <https://www.gnu.org/licenses/>.
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of these hook files and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
Preamble
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
The GNU Affero General Public License is a free, copyleft license for
|
||||
software and other kinds of works, specifically designed to ensure
|
||||
cooperation with the community in the case of network server software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
The licenses for most software and other practical works are designed
|
||||
to take away your freedom to share and change the works. By contrast,
|
||||
our General Public Licenses are intended to guarantee your freedom to
|
||||
share and change all versions of a program--to make sure it remains free
|
||||
software for all its users.
|
||||
|
||||
## Contributions
|
||||
When we speak of free software, we are referring to freedom, not
|
||||
price. Our General Public Licenses are designed to make sure that you
|
||||
have the freedom to distribute copies of free software (and charge for
|
||||
them if you wish), that you receive source code or can get it if you
|
||||
want it, that you can change the software or use pieces of it in new
|
||||
free programs, and that you know you can do these things.
|
||||
|
||||
By submitting pull requests for hook files or documentation, you agree to license your contributions under the MIT License.
|
||||
Developers that use our General Public Licenses protect your rights
|
||||
with two steps: (1) assert copyright on the software, and (2) offer
|
||||
you this License which gives you legal permission to copy, distribute
|
||||
and/or modify the software.
|
||||
|
||||
## Trademark
|
||||
A secondary benefit of defending all users' freedom is that
|
||||
improvements made in alternate versions of the program, if they
|
||||
receive widespread use, become available for other developers to
|
||||
incorporate. Many developers of free software are heartened and
|
||||
encouraged by the resulting cooperation. However, in the case of
|
||||
software used on network servers, this result may fail to come about.
|
||||
The GNU General Public License permits making a modified version and
|
||||
letting the public access it on a server without ever releasing its
|
||||
source code to the public.
|
||||
|
||||
"Claude Mem" is a trademark of Alex Newman. You may use the name when referring to this software, but not in a way that implies endorsement or affiliation.
|
||||
The GNU Affero General Public License is designed specifically to
|
||||
ensure that, in such cases, the modified source code becomes available
|
||||
to the community. It requires the operator of a network server to
|
||||
provide the source code of the modified version running there to the
|
||||
users of that server. Therefore, public use of a modified version, on
|
||||
a publicly accessible server, gives the public access to the source
|
||||
code of the modified version.
|
||||
|
||||
An older license, called the Affero General Public License and
|
||||
published by Affero, was designed to accomplish similar goals. This is
|
||||
a different license, not a version of the Affero GPL, but Affero has
|
||||
released a new version of the Affero GPL which permits relicensing under
|
||||
this license.
|
||||
|
||||
The precise terms and conditions for copying, distribution and
|
||||
modification follow.
|
||||
|
||||
TERMS AND CONDITIONS
|
||||
|
||||
0. Definitions.
|
||||
|
||||
"This License" refers to version 3 of the GNU Affero General Public License.
|
||||
|
||||
"Copyright" also means copyright-like laws that apply to other kinds of
|
||||
works, such as semiconductor masks.
|
||||
|
||||
"The Program" refers to any copyrightable work licensed under this
|
||||
License. Each licensee is addressed as "you". "Licensees" and
|
||||
"recipients" may be individuals or organizations.
|
||||
|
||||
To "modify" a work means to copy from or adapt all or part of the work
|
||||
in a fashion requiring copyright permission, other than the making of an
|
||||
exact copy. The resulting work is called a "modified version" of the
|
||||
earlier work or a work "based on" the earlier work.
|
||||
|
||||
A "covered work" means either the unmodified Program or a work based
|
||||
on the Program.
|
||||
|
||||
To "propagate" a work means to do anything with it that, without
|
||||
permission, would make you directly or secondarily liable for
|
||||
infringement under applicable copyright law, except executing it on a
|
||||
computer or modifying a private copy. Propagation includes copying,
|
||||
distribution (with or without modification), making available to the
|
||||
public, and in some countries other activities as well.
|
||||
|
||||
To "convey" a work means any kind of propagation that enables other
|
||||
parties to make or receive copies. Mere interaction with a user through
|
||||
a computer network, with no transfer of a copy, is not conveying.
|
||||
|
||||
An interactive user interface displays "Appropriate Legal Notices"
|
||||
to the extent that it includes a convenient and prominently visible
|
||||
feature that (1) displays an appropriate copyright notice, and (2)
|
||||
tells the user that there is no warranty for the work (except to the
|
||||
extent that warranties are provided), that licensees may convey the
|
||||
work under this License, and how to view a copy of this License. If
|
||||
the interface presents a list of user commands or options, such as a
|
||||
menu, a prominent item in the list meets this criterion.
|
||||
|
||||
1. Source Code.
|
||||
|
||||
The "source code" for a work means the preferred form of the work
|
||||
for making modifications to it. "Object code" means any non-source
|
||||
form of a work.
|
||||
|
||||
A "Standard Interface" means an interface that either is an official
|
||||
standard defined by a recognized standards body, or, in the case of
|
||||
interfaces specified for a particular programming language, one that
|
||||
is widely used among developers working in that language.
|
||||
|
||||
The "System Libraries" of an executable work include anything, other
|
||||
than the work as a whole, that (a) is included in the normal form of
|
||||
packaging a Major Component, but which is not part of that Major
|
||||
Component, and (b) serves only to enable use of the work with that
|
||||
Major Component, or to implement a Standard Interface for which an
|
||||
implementation is available to the public in source code form. A
|
||||
"Major Component", in this context, means a major essential component
|
||||
(kernel, window system, and so on) of the specific operating system
|
||||
(if any) on which the executable work runs, or a compiler used to
|
||||
produce the work, or an object code interpreter used to run it.
|
||||
|
||||
The "Corresponding Source" for a work in object code form means all
|
||||
the source code needed to generate, install, and (for an executable
|
||||
work) run the object code and to modify the work, including scripts to
|
||||
control those activities. However, it does not include the work's
|
||||
System Libraries, or general-purpose tools or generally available free
|
||||
programs which are used unmodified in performing those activities but
|
||||
which are not part of the work. For example, Corresponding Source
|
||||
includes interface definition files associated with source files for
|
||||
the work, and the source code for shared libraries and dynamically
|
||||
linked subprograms that the work is specifically designed to require,
|
||||
such as by intimate data communication or control flow between those
|
||||
subprograms and other parts of the work.
|
||||
|
||||
The Corresponding Source need not include anything that users
|
||||
can regenerate automatically from other parts of the Corresponding
|
||||
Source.
|
||||
|
||||
The Corresponding Source for a work in source code form is that
|
||||
same work.
|
||||
|
||||
2. Basic Permissions.
|
||||
|
||||
All rights granted under this License are granted for the term of
|
||||
copyright on the Program, and are irrevocable provided the stated
|
||||
conditions are met. This License explicitly affirms your unlimited
|
||||
permission to run the unmodified Program. The output from running a
|
||||
covered work is covered by this License only if the output, given its
|
||||
content, constitutes a covered work. This License acknowledges your
|
||||
rights of fair use or other equivalent, as provided by copyright law.
|
||||
|
||||
You may make, run and propagate covered works that you do not
|
||||
convey, without conditions so long as your license otherwise remains
|
||||
in force. You may convey covered works to others for the sole purpose
|
||||
of having them make modifications exclusively for you, or provide you
|
||||
with facilities for running those works, provided that you comply with
|
||||
the terms of this License in conveying all material for which you do
|
||||
not control copyright. Those thus making or running the covered works
|
||||
for you must do so exclusively on your behalf, under your direction
|
||||
and control, on terms that prohibit them from making any copies of
|
||||
your copyrighted material outside their relationship with you.
|
||||
|
||||
Conveying under any other circumstances is permitted solely under
|
||||
the conditions stated below. Sublicensing is not allowed; section 10
|
||||
makes it unnecessary.
|
||||
|
||||
3. Protecting Users' Legal Rights From Anti-Circumvention Law.
|
||||
|
||||
No covered work shall be deemed part of an effective technological
|
||||
measure under any applicable law fulfilling obligations under article
|
||||
11 of the WIPO copyright treaty adopted on 20 December 1996, or
|
||||
similar laws prohibiting or restricting circumvention of such
|
||||
measures.
|
||||
|
||||
When you convey a covered work, you waive any legal power to forbid
|
||||
circumvention of technological measures to the extent such circumvention
|
||||
is effected by exercising rights under this License with respect to
|
||||
the covered work, and you disclaim any intention to limit operation or
|
||||
modification of the work as a means of enforcing, against the work's
|
||||
users, your or third parties' legal rights to forbid circumvention of
|
||||
technological measures.
|
||||
|
||||
4. Conveying Verbatim Copies.
|
||||
|
||||
You may convey verbatim copies of the Program's source code as you
|
||||
receive it, in any medium, provided that you conspicuously and
|
||||
appropriately publish on each copy an appropriate copyright notice;
|
||||
keep intact all notices stating that this License and any
|
||||
non-permissive terms added in accord with section 7 apply to the code;
|
||||
keep intact all notices of the absence of any warranty; and give all
|
||||
recipients a copy of this License along with the Program.
|
||||
|
||||
You may charge any price or no price for each copy that you convey,
|
||||
and you may offer support or warranty protection for a fee.
|
||||
|
||||
5. Conveying Modified Source Versions.
|
||||
|
||||
You may convey a work based on the Program, or the modifications to
|
||||
produce it from the Program, in the form of source code under the
|
||||
terms of section 4, provided that you also meet all of these conditions:
|
||||
|
||||
a) The work must carry prominent notices stating that you modified
|
||||
it, and giving a relevant date.
|
||||
|
||||
b) The work must carry prominent notices stating that it is
|
||||
released under this License and any conditions added under section
|
||||
7. This requirement modifies the requirement in section 4 to
|
||||
"keep intact all notices".
|
||||
|
||||
c) You must license the entire work, as a whole, under this
|
||||
License to anyone who comes into possession of a copy. This
|
||||
License will therefore apply, along with any applicable section 7
|
||||
additional terms, to the whole of the work, and all its parts,
|
||||
regardless of how they are packaged. This License gives no
|
||||
permission to license the work in any other way, but it does not
|
||||
invalidate such permission if you have separately received it.
|
||||
|
||||
d) If the work has interactive user interfaces, each must display
|
||||
Appropriate Legal Notices; however, if the Program has interactive
|
||||
interfaces that do not display Appropriate Legal Notices, your
|
||||
work need not make them do so.
|
||||
|
||||
A compilation of a covered work with other separate and independent
|
||||
works, which are not by their nature extensions of the covered work,
|
||||
and which are not combined with it such as to form a larger program,
|
||||
in or on a volume of a storage or distribution medium, is called an
|
||||
"aggregate" if the compilation and its resulting copyright are not
|
||||
used to limit the access or legal rights of the compilation's users
|
||||
beyond what the individual works permit. Inclusion of a covered work
|
||||
in an aggregate does not cause this License to apply to the other
|
||||
parts of the aggregate.
|
||||
|
||||
6. Conveying Non-Source Forms.
|
||||
|
||||
You may convey a covered work in object code form under the terms
|
||||
of sections 4 and 5, provided that you also convey the
|
||||
machine-readable Corresponding Source under the terms of this License,
|
||||
in one of these ways:
|
||||
|
||||
a) Convey the object code in, or embodied in, a physical product
|
||||
(including a physical distribution medium), accompanied by the
|
||||
Corresponding Source fixed on a durable physical medium
|
||||
customarily used for software interchange.
|
||||
|
||||
b) Convey the object code in, or embodied in, a physical product
|
||||
(including a physical distribution medium), accompanied by a
|
||||
written offer, valid for at least three years and valid for as
|
||||
long as you offer spare parts or customer support for that product
|
||||
model, to give anyone who possesses the object code either (1) a
|
||||
copy of the Corresponding Source for all the software in the
|
||||
product that is covered by this License, on a durable physical
|
||||
medium customarily used for software interchange, for a price no
|
||||
more than your reasonable cost of physically performing this
|
||||
conveying of source, or (2) access to copy the
|
||||
Corresponding Source from a network server at no charge.
|
||||
|
||||
c) Convey individual copies of the object code with a copy of the
|
||||
written offer to provide the Corresponding Source. This
|
||||
alternative is allowed only occasionally and noncommercially, and
|
||||
only if you received the object code with such an offer, in accord
|
||||
with subsection 6b.
|
||||
|
||||
d) Convey the object code by offering access from a designated
|
||||
place (gratis or for a charge), and offer equivalent access to the
|
||||
Corresponding Source in the same way through the same place at no
|
||||
further charge. You need not require recipients to copy the
|
||||
Corresponding Source along with the object code. If the place to
|
||||
copy the object code is a network server, the Corresponding Source
|
||||
may be on a different server (operated by you or a third party)
|
||||
that supports equivalent copying facilities, provided you maintain
|
||||
clear directions next to the object code saying where to find the
|
||||
Corresponding Source. Regardless of what server hosts the
|
||||
Corresponding Source, you remain obligated to ensure that it is
|
||||
available for as long as needed to satisfy these requirements.
|
||||
|
||||
e) Convey the object code using peer-to-peer transmission, provided
|
||||
you inform other peers where the object code and Corresponding
|
||||
Source of the work are being offered to the general public at no
|
||||
charge under subsection 6d.
|
||||
|
||||
A separable portion of the object code, whose source code is excluded
|
||||
from the Corresponding Source as a System Library, need not be
|
||||
included in conveying the object code work.
|
||||
|
||||
A "User Product" is either (1) a "consumer product", which means any
|
||||
tangible personal property which is normally used for personal, family,
|
||||
or household purposes, or (2) anything designed or sold for incorporation
|
||||
into a dwelling. In determining whether a product is a consumer product,
|
||||
doubtful cases shall be resolved in favor of coverage. For a particular
|
||||
product received by a particular user, "normally used" refers to a
|
||||
typical or common use of that class of product, regardless of the status
|
||||
of the particular user or of the way in which the particular user
|
||||
actually uses, or expects or is expected to use, the product. A product
|
||||
is a consumer product regardless of whether the product has substantial
|
||||
commercial, industrial or non-consumer uses, unless such uses represent
|
||||
the only significant mode of use of the product.
|
||||
|
||||
"Installation Information" for a User Product means any methods,
|
||||
procedures, authorization keys, or other information required to install
|
||||
and execute modified versions of a covered work in that User Product from
|
||||
a modified version of its Corresponding Source. The information must
|
||||
suffice to ensure that the continued functioning of the modified object
|
||||
code is in no case prevented or interfered with solely because
|
||||
modification has been made.
|
||||
|
||||
If you convey an object code work under this section in, or with, or
|
||||
specifically for use in, a User Product, and the conveying occurs as
|
||||
part of a transaction in which the right of possession and use of the
|
||||
User Product is transferred to the recipient in perpetuity or for a
|
||||
fixed term (regardless of how the transaction is characterized), the
|
||||
Corresponding Source conveyed under this section must be accompanied
|
||||
by the Installation Information. But this requirement does not apply
|
||||
if neither you nor any third party retains the ability to install
|
||||
modified object code on the User Product (for example, the work has
|
||||
been installed in ROM).
|
||||
|
||||
The requirement to provide Installation Information does not include a
|
||||
requirement to continue to provide support service, warranty, or updates
|
||||
for a work that has been modified or installed by the recipient, or for
|
||||
the User Product in which it has been modified or installed. Access to a
|
||||
network may be denied when the modification itself materially and
|
||||
adversely affects the operation of the network or violates the rules and
|
||||
protocols for communication across the network.
|
||||
|
||||
Corresponding Source conveyed, and Installation Information provided,
|
||||
in accord with this section must be in a format that is publicly
|
||||
documented (and with an implementation available to the public in
|
||||
source code form), and must require no special password or key for
|
||||
unpacking, reading or copying.
|
||||
|
||||
7. Additional Terms.
|
||||
|
||||
"Additional permissions" are terms that supplement the terms of this
|
||||
License by making exceptions from one or more of its conditions.
|
||||
Additional permissions that are applicable to the entire Program shall
|
||||
be treated as though they were included in this License, to the extent
|
||||
that they are valid under applicable law. If additional permissions
|
||||
apply only to part of the Program, that part may be used separately
|
||||
under those permissions, but the entire Program remains governed by
|
||||
this License without regard to the additional permissions.
|
||||
|
||||
When you convey a copy of a covered work, you may at your option
|
||||
remove any additional permissions from that copy, or from any part of
|
||||
it. (Additional permissions may be written to require their own
|
||||
removal in certain cases when you modify the work.) You may place
|
||||
additional permissions on material, added by you to a covered work,
|
||||
for which you have or can give appropriate copyright permission.
|
||||
|
||||
Notwithstanding any other provision of this License, for material you
|
||||
add to a covered work, you may (if authorized by the copyright holders of
|
||||
that material) supplement the terms of this License with terms:
|
||||
|
||||
a) Disclaiming warranty or limiting liability differently from the
|
||||
terms of sections 15 and 16 of this License; or
|
||||
|
||||
b) Requiring preservation of specified reasonable legal notices or
|
||||
author attributions in that material or in the Appropriate Legal
|
||||
Notices displayed by works containing it; or
|
||||
|
||||
c) Prohibiting misrepresentation of the origin of that material, or
|
||||
requiring that modified versions of such material be marked in
|
||||
reasonable ways as different from the original version; or
|
||||
|
||||
d) Limiting the use for publicity purposes of names of licensors or
|
||||
authors of the material; or
|
||||
|
||||
e) Declining to grant rights under trademark law for use of some
|
||||
trade names, trademarks, or service marks; or
|
||||
|
||||
f) Requiring indemnification of licensors and authors of that
|
||||
material by anyone who conveys the material (or modified versions of
|
||||
it) with contractual assumptions of liability to the recipient, for
|
||||
any liability that these contractual assumptions directly impose on
|
||||
those licensors and authors.
|
||||
|
||||
All other non-permissive additional terms are considered "further
|
||||
restrictions" within the meaning of section 10. If the Program as you
|
||||
received it, or any part of it, contains a notice stating that it is
|
||||
governed by this License along with a term that is a further
|
||||
restriction, you may remove that term. If a license document contains
|
||||
a further restriction but permits relicensing or conveying under this
|
||||
License, you may add to a covered work material governed by the terms
|
||||
of that license document, provided that the further restriction does
|
||||
not survive such relicensing or conveying.
|
||||
|
||||
If you add terms to a covered work in accord with this section, you
|
||||
must place, in the relevant source files, a statement of the
|
||||
additional terms that apply to those files, or a notice indicating
|
||||
where to find the applicable terms.
|
||||
|
||||
Additional terms, permissive or non-permissive, may be stated in the
|
||||
form of a separately written license, or stated as exceptions;
|
||||
the above requirements apply either way.
|
||||
|
||||
8. Termination.
|
||||
|
||||
You may not propagate or modify a covered work except as expressly
|
||||
provided under this License. Any attempt otherwise to propagate or
|
||||
modify it is void, and will automatically terminate your rights under
|
||||
this License (including any patent licenses granted under the third
|
||||
paragraph of section 11).
|
||||
|
||||
However, if you cease all violation of this License, then your
|
||||
license from a particular copyright holder is reinstated (a)
|
||||
provisionally, unless and until the copyright holder explicitly and
|
||||
finally terminates your license, and (b) permanently, if the copyright
|
||||
holder fails to notify you of the violation by some reasonable means
|
||||
prior to 60 days after the cessation.
|
||||
|
||||
Moreover, your license from a particular copyright holder is
|
||||
reinstated permanently if the copyright holder notifies you of the
|
||||
violation by some reasonable means, this is the first time you have
|
||||
received notice of violation of this License (for any work) from that
|
||||
copyright holder, and you cure the violation prior to 30 days after
|
||||
your receipt of the notice.
|
||||
|
||||
Termination of your rights under this section does not terminate the
|
||||
licenses of parties who have received copies or rights from you under
|
||||
this License. If your rights have been terminated and not permanently
|
||||
reinstated, you do not qualify to receive new licenses for the same
|
||||
material under section 10.
|
||||
|
||||
9. Acceptance Not Required for Having Copies.
|
||||
|
||||
You are not required to accept this License in order to receive or
|
||||
run a copy of the Program. Ancillary propagation of a covered work
|
||||
occurring solely as a consequence of using peer-to-peer transmission
|
||||
to receive a copy likewise does not require acceptance. However,
|
||||
nothing other than this License grants you permission to propagate or
|
||||
modify any covered work. These actions infringe copyright if you do
|
||||
not accept this License. Therefore, by modifying or propagating a
|
||||
covered work, you indicate your acceptance of this License to do so.
|
||||
|
||||
10. Automatic Licensing of Downstream Recipients.
|
||||
|
||||
Each time you convey a covered work, the recipient automatically
|
||||
receives a license from the original licensors, to run, modify and
|
||||
propagate that work, subject to this License. You are not responsible
|
||||
for enforcing compliance by third parties with this License.
|
||||
|
||||
An "entity transaction" is a transaction transferring control of an
|
||||
organization, or substantially all assets of one, or subdividing an
|
||||
organization, or merging organizations. If propagation of a covered
|
||||
work results from an entity transaction, each party to that
|
||||
transaction who receives a copy of the work also receives whatever
|
||||
licenses to the work the party's predecessor in interest had or could
|
||||
give under the previous paragraph, plus a right to possession of the
|
||||
Corresponding Source of the work from the predecessor in interest, if
|
||||
the predecessor has it or can get it with reasonable efforts.
|
||||
|
||||
You may not impose any further restrictions on the exercise of the
|
||||
rights granted or affirmed under this License. For example, you may
|
||||
not impose a license fee, royalty, or other charge for exercise of
|
||||
rights granted under this License, and you may not initiate litigation
|
||||
(including a cross-claim or counterclaim in a lawsuit) alleging that
|
||||
any patent claim is infringed by making, using, selling, offering for
|
||||
sale, or importing the Program or any portion of it.
|
||||
|
||||
11. Patents.
|
||||
|
||||
A "contributor" is a copyright holder who authorizes use under this
|
||||
License of the Program or a work on which the Program is based. The
|
||||
work thus licensed is called the contributor's "contributor version".
|
||||
|
||||
A contributor's "essential patent claims" are all patent claims
|
||||
owned or controlled by the contributor, whether already acquired or
|
||||
hereafter acquired, that would be infringed by some manner, permitted
|
||||
by this License, of making, using, or selling its contributor version,
|
||||
but do not include claims that would be infringed only as a
|
||||
consequence of further modification of the contributor version. For
|
||||
purposes of this definition, "control" includes the right to grant
|
||||
patent sublicenses in a manner consistent with the requirements of
|
||||
this License.
|
||||
|
||||
Each contributor grants you a non-exclusive, worldwide, royalty-free
|
||||
patent license under the contributor's essential patent claims, to
|
||||
make, use, sell, offer for sale, import and otherwise run, modify and
|
||||
propagate the contents of its contributor version.
|
||||
|
||||
In the following three paragraphs, a "patent license" is any express
|
||||
agreement or commitment, however denominated, not to enforce a patent
|
||||
(such as an express permission to practice a patent or covenant not to
|
||||
sue for patent infringement). To "grant" such a patent license to a
|
||||
party means to make such an agreement or commitment not to enforce a
|
||||
patent against the party.
|
||||
|
||||
If you convey a covered work, knowingly relying on a patent license,
|
||||
and the Corresponding Source of the work is not available for anyone
|
||||
to copy, free of charge and under the terms of this License, through a
|
||||
publicly available network server or other readily accessible means,
|
||||
then you must either (1) cause the Corresponding Source to be so
|
||||
available, or (2) arrange to deprive yourself of the benefit of the
|
||||
patent license for this particular work, or (3) arrange, in a manner
|
||||
consistent with the requirements of this License, to extend the patent
|
||||
license to downstream recipients. "Knowingly relying" means you have
|
||||
actual knowledge that, but for the patent license, your conveying the
|
||||
covered work in a country, or your recipient's use of the covered work
|
||||
in a country, would infringe one or more identifiable patents in that
|
||||
country that you have reason to believe are valid.
|
||||
|
||||
If, pursuant to or in connection with a single transaction or
|
||||
arrangement, you convey, or propagate by procuring conveyance of, a
|
||||
covered work, and grant a patent license to some of the parties
|
||||
receiving the covered work authorizing them to use, propagate, modify
|
||||
or convey a specific copy of the covered work, then the patent license
|
||||
you grant is automatically extended to all recipients of the covered
|
||||
work and works based on it.
|
||||
|
||||
A patent license is "discriminatory" if it does not include within
|
||||
the scope of its coverage, prohibits the exercise of, or is
|
||||
conditioned on the non-exercise of one or more of the rights that are
|
||||
specifically granted under this License. You may not convey a covered
|
||||
work if you are a party to an arrangement with a third party that is
|
||||
in the business of distributing software, under which you make payment
|
||||
to the third party based on the extent of your activity of conveying
|
||||
the work, and under which the third party grants, to any of the
|
||||
parties who would receive the covered work from you, a discriminatory
|
||||
patent license (a) in connection with copies of the covered work
|
||||
conveyed by you (or copies made from those copies), or (b) primarily
|
||||
for and in connection with specific products or compilations that
|
||||
contain the covered work, unless you entered into that arrangement,
|
||||
or that patent license was granted, prior to 28 March 2007.
|
||||
|
||||
Nothing in this License shall be construed as excluding or limiting
|
||||
any implied license or other defenses to infringement that may
|
||||
otherwise be available to you under applicable patent law.
|
||||
|
||||
12. No Surrender of Others' Freedom.
|
||||
|
||||
If conditions are imposed on you (whether by court order, agreement or
|
||||
otherwise) that contradict the conditions of this License, they do not
|
||||
excuse you from the conditions of this License. If you cannot convey a
|
||||
covered work so as to satisfy simultaneously your obligations under this
|
||||
License and any other pertinent obligations, then as a consequence you may
|
||||
not convey it at all. For example, if you agree to terms that obligate you
|
||||
to collect a royalty for further conveying from those to whom you convey
|
||||
the Program, the only way you could satisfy both those terms and this
|
||||
License would be to refrain entirely from conveying the Program.
|
||||
|
||||
13. Remote Network Interaction; Use with the GNU General Public License.
|
||||
|
||||
Notwithstanding any other provision of this License, if you modify the
|
||||
Program, your modified version must prominently offer all users
|
||||
interacting with it remotely through a computer network (if your version
|
||||
supports such interaction) an opportunity to receive the Corresponding
|
||||
Source of your version by providing access to the Corresponding Source
|
||||
from a network server at no charge, through some standard or customary
|
||||
means of facilitating copying of software. This Corresponding Source
|
||||
shall include the Corresponding Source for any work covered by version 3
|
||||
of the GNU General Public License that is incorporated pursuant to the
|
||||
following paragraph.
|
||||
|
||||
Notwithstanding any other provision of this License, you have
|
||||
permission to link or combine any covered work with a work licensed
|
||||
under version 3 of the GNU General Public License into a single
|
||||
combined work, and to convey the resulting work. The terms of this
|
||||
License will continue to apply to the part which is the covered work,
|
||||
but the work with which it is combined will remain governed by version
|
||||
3 of the GNU General Public License.
|
||||
|
||||
14. Revised Versions of this License.
|
||||
|
||||
The Free Software Foundation may publish revised and/or new versions of
|
||||
the GNU Affero General Public License from time to time. Such new versions
|
||||
will be similar in spirit to the present version, but may differ in detail to
|
||||
address new problems or concerns.
|
||||
|
||||
Each version is given a distinguishing version number. If the
|
||||
Program specifies that a certain numbered version of the GNU Affero General
|
||||
Public License "or any later version" applies to it, you have the
|
||||
option of following the terms and conditions either of that numbered
|
||||
version or of any later version published by the Free Software
|
||||
Foundation. If the Program does not specify a version number of the
|
||||
GNU Affero General Public License, you may choose any version ever published
|
||||
by the Free Software Foundation.
|
||||
|
||||
If the Program specifies that a proxy can decide which future
|
||||
versions of the GNU Affero General Public License can be used, that proxy's
|
||||
public statement of acceptance of a version permanently authorizes you
|
||||
to choose that version for the Program.
|
||||
|
||||
Later license versions may give you additional or different
|
||||
permissions. However, no additional obligations are imposed on any
|
||||
author or copyright holder as a result of your choosing to follow a
|
||||
later version.
|
||||
|
||||
15. Disclaimer of Warranty.
|
||||
|
||||
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
|
||||
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
|
||||
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
|
||||
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
|
||||
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
||||
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
|
||||
IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
|
||||
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
|
||||
|
||||
16. Limitation of Liability.
|
||||
|
||||
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
|
||||
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
|
||||
THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
|
||||
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
|
||||
USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
|
||||
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
|
||||
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
|
||||
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
|
||||
SUCH DAMAGES.
|
||||
|
||||
17. Interpretation of Sections 15 and 16.
|
||||
|
||||
If the disclaimer of warranty and limitation of liability provided
|
||||
above cannot be given local legal effect according to their terms,
|
||||
reviewing courts shall apply local law that most closely approximates
|
||||
an absolute waiver of all civil liability in connection with the
|
||||
Program, unless a warranty or assumption of liability accompanies a
|
||||
copy of the Program in return for a fee.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
@@ -1,215 +1,86 @@
|
||||
# Claude Memory System (claude-mem)
|
||||
# 🧠 Claude Memory System (claude-mem)
|
||||
|
||||
**Truth + Context = Clarity**
|
||||
## Remember that one thing? Neither do we… but `claude-mem` does! 😵💫
|
||||
|
||||
A revolutionary memory system that transforms your Claude Code conversations into a persistent, intelligent knowledge base. Never lose valuable insights, code patterns, or debugging solutions again. Your AI assistant finally has a memory that spans across all your projects and sessions.
|
||||
Stop repeating yourself. `claude-mem` remembers what you and Claude Code figure out, so every new chat starts smarter than the last.
|
||||
|
||||
## 🚀 Why Claude-Mem?
|
||||
## ⚡️ 10‑Second Setup
|
||||
|
||||
### The Problem We Solve
|
||||
- **Lost Context**: Starting every Claude Code session from scratch
|
||||
- **Repeated Explanations**: Re-describing your codebase and architecture repeatedly
|
||||
- **Fragmented Knowledge**: Valuable insights scattered across hundreds of conversations
|
||||
- **Context Switching**: Losing progress when switching between projects or devices
|
||||
- **Knowledge Decay**: Brilliant solutions forgotten and re-discovered multiple times
|
||||
|
||||
### The Claude-Mem Solution
|
||||
Transform your Claude Code experience from forgetful to persistent, from isolated sessions to connected knowledge, from starting over to building upon previous insights.
|
||||
|
||||
## ✨ Key Features
|
||||
|
||||
### 🧠 **Intelligent Memory Compression**
|
||||
- Automatically extracts key learnings from your Claude Code conversations
|
||||
- Identifies patterns, architectural decisions, and breakthrough moments
|
||||
- Compresses hours of conversation into searchable, actionable knowledge
|
||||
- Uses advanced AI analysis to understand context and significance
|
||||
|
||||
### 🔄 **Seamless Integration**
|
||||
- **One-command setup**: `claude-mem install` and you're ready
|
||||
- **Zero friction**: Works invisibly in the background
|
||||
- **Automatic triggers**: Memory compression on `/compact` and `/clear`
|
||||
- **Instant context loading**: New sessions start with relevant memories
|
||||
|
||||
### 🎯 **Smart Context Loading**
|
||||
- Loads relevant memories when starting new sessions
|
||||
- Project-aware context selection
|
||||
- Semantic search finds related knowledge across all sessions
|
||||
- Prevents re-explaining the same concepts repeatedly
|
||||
|
||||
### 📚 **Comprehensive Knowledge Base**
|
||||
- Stores technical implementations, bug fixes, and solutions
|
||||
- Captures design patterns and architectural decisions
|
||||
- Remembers tool configurations and setup procedures
|
||||
- Archives complete conversation transcripts for detailed reference
|
||||
|
||||
### 🔍 **Powerful Search & Retrieval**
|
||||
- Vector-based semantic search finds related concepts
|
||||
- Keyword search for specific terms and technologies
|
||||
- Project filtering to focus on relevant memories
|
||||
- Time-based filtering to find recent insights
|
||||
|
||||
## 🛠 Installation & Setup
|
||||
|
||||
### Quick Install
|
||||
```bash
|
||||
# Install globally
|
||||
npm install -g claude-mem
|
||||
|
||||
# Set up Claude Code integration
|
||||
claude-mem install
|
||||
|
||||
# Restart Claude Code to activate
|
||||
npm install -g claude-mem && claude-mem install
|
||||
```
|
||||
|
||||
### Alternative Installation
|
||||
That’s it. Restart Claude Code and you’re good. No config. No tedious setup or dependencies.
|
||||
|
||||
## ✨ What You Get
|
||||
|
||||
- Remembers key insights from your chats with Claude Code
|
||||
- Starts new sessions with the right context
|
||||
- Works quietly in the background
|
||||
- One-command install and status check
|
||||
|
||||
## 🗑️ Smart Trash™ (Your Panic Button)
|
||||
|
||||
Delete something by accident? It’s not gone.
|
||||
- Everything goes to `~/.claude-mem/trash/`
|
||||
- Restore with a single command: `claude-mem restore`
|
||||
- Timestamped so you can see when things moved
|
||||
|
||||
## 🎯 Why It’s Useful
|
||||
|
||||
- No more re-explaining your project over and over
|
||||
- Pick up exactly where you left off
|
||||
- Find past solutions fast when you face a familiar bug
|
||||
- Your knowledge compounds the more you use it
|
||||
|
||||
## 🧭 Minimal Commands You’ll Ever Need
|
||||
|
||||
```bash
|
||||
# Use without installing globally
|
||||
npx claude-mem install
|
||||
claude-mem install # Set up/repair integration
|
||||
claude-mem status # Check everything’s working
|
||||
claude-mem load-context # Peek at what it remembers
|
||||
claude-mem logs # If you’re curious
|
||||
claude-mem uninstall # Remove hooks
|
||||
|
||||
# Extras
|
||||
claude-mem trash-view # See what’s in Smart Trash™
|
||||
claude-mem restore # Restore deleted items
|
||||
```
|
||||
|
||||
### Verification
|
||||
```bash
|
||||
# Check installation status
|
||||
claude-mem status
|
||||
```
|
||||
|
||||
## 💻 How It Works
|
||||
|
||||
### The Memory Lifecycle
|
||||
|
||||
1. **🎬 Session Start**: Claude-mem loads relevant context from your knowledge base
|
||||
2. **💬 Active Session**: You work normally in Claude Code - no changes needed
|
||||
3. **🗜️ Memory Compression**: Use `/compact` or `/clear` to trigger intelligent compression
|
||||
4. **🧠 Knowledge Extraction**: AI analysis extracts key learnings and patterns
|
||||
5. **💾 Persistent Storage**: Memories stored in searchable vector database
|
||||
6. **🔄 Context Ready**: Next session starts with relevant memories loaded
|
||||
|
||||
### Technical Architecture
|
||||
|
||||
- **Vector Database**: ChromaDB for semantic search and storage
|
||||
- **MCP Integration**: Model Context Protocol for Claude Code communication
|
||||
- **AI Analysis**: Advanced prompt engineering for knowledge extraction
|
||||
- **Local Storage**: All data stored locally in `~/.claude-mem/`
|
||||
|
||||
## 📋 Commands Reference
|
||||
|
||||
### Core Commands
|
||||
```bash
|
||||
claude-mem install # Set up Claude Code integration
|
||||
claude-mem status # Check system status and configuration
|
||||
claude-mem load-context # View and search stored memories
|
||||
claude-mem logs # View system logs and debug information
|
||||
claude-mem uninstall # Remove Claude Code hooks
|
||||
```
|
||||
|
||||
### Advanced Usage
|
||||
```bash
|
||||
claude-mem compress <file> # Manually compress a transcript file
|
||||
claude-mem restore # Restore from backups
|
||||
claude-mem trash-view # View deleted files (Smart Trash feature)
|
||||
```
|
||||
|
||||
## 📁 Storage Structure
|
||||
|
||||
Your claude-mem data is organized in `~/.claude-mem/`:
|
||||
## 📁 Where Stuff Lives (super simple)
|
||||
|
||||
```
|
||||
~/.claude-mem/
|
||||
├── index/ # ChromaDB vector database
|
||||
├── archives/ # Original conversation transcripts
|
||||
├── hooks/ # Claude Code integration scripts
|
||||
├── trash/ # Smart Trash (deleted files)
|
||||
└── logs/ # System logs and debug information
|
||||
├── index/ # memory index
|
||||
├── archives/ # transcripts
|
||||
├── hooks/ # integration bits
|
||||
├── trash/ # Smart Trash™
|
||||
└── logs/ # diagnostics
|
||||
```
|
||||
|
||||
## 🌟 Real-World Benefits
|
||||
## ✅ Requirements
|
||||
|
||||
### For Individual Developers
|
||||
- **Faster Problem Solving**: Find solutions you've used before instantly
|
||||
- **Knowledge Accumulation**: Build expertise that persists across projects
|
||||
- **Context Continuity**: Pick up where you left off, even weeks later
|
||||
- **Pattern Recognition**: See how you've solved similar problems before
|
||||
- Node.js 18+
|
||||
- Claude Code
|
||||
|
||||
### For Teams (Coming Soon)
|
||||
- **Shared Knowledge**: Team-wide memory accessible to all members
|
||||
- **Onboarding Acceleration**: New team members access collective knowledge
|
||||
- **Best Practices**: Capture and share proven solutions
|
||||
- **Institutional Memory**: Prevent knowledge loss when team members leave
|
||||
## 🆘 If Something’s Weird
|
||||
|
||||
## 🚀 Coming Soon: Cloud Sync
|
||||
|
||||
### Individual Plan ($9.95/month)
|
||||
- **Multi-device sync**: Access your memories on any device
|
||||
- **Cloud backup**: Never lose your knowledge base
|
||||
- **Enhanced search**: Advanced filtering and semantic search
|
||||
- **API access**: Integrate with your own tools and workflows
|
||||
|
||||
### Team Plan ($29.95/month, 3+ seats)
|
||||
- **Shared memories**: Team-wide knowledge base
|
||||
- **Role-based access**: Control what memories are shared
|
||||
- **Admin dashboard**: Manage team members and usage
|
||||
- **Priority support**: Direct access to our engineering team
|
||||
|
||||
[**Join the waitlist**](https://claude-mem.ai) for early access to cloud features.
|
||||
|
||||
## 🛡️ Privacy & Security
|
||||
|
||||
- **Local-first**: All data stored locally by default
|
||||
- **No tracking**: We don't collect or transmit your conversations
|
||||
- **Your data**: You own and control your knowledge base
|
||||
- **Open architecture**: ChromaDB and MCP are open standards
|
||||
|
||||
## 🆘 Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Hook not triggering?**
|
||||
```bash
|
||||
claude-mem status # Check installation
|
||||
claude-mem install --force # Reinstall hooks
|
||||
claude-mem status # quick health check
|
||||
claude-mem install --force # fixes most issues
|
||||
```
|
||||
|
||||
**Context not loading?**
|
||||
```bash
|
||||
claude-mem load-context # Verify memories exist
|
||||
claude-mem logs # Check for errors
|
||||
```
|
||||
|
||||
**Performance issues?**
|
||||
```bash
|
||||
# ChromaDB maintenance (if needed)
|
||||
claude-mem status # Check memory usage
|
||||
```
|
||||
|
||||
## 🔧 Requirements
|
||||
|
||||
- **Node.js**: 18.0 or higher
|
||||
- **Claude Code**: Latest version recommended
|
||||
- **Storage**: ~100MB for typical usage
|
||||
- **Memory**: 2GB RAM minimum for large knowledge bases
|
||||
|
||||
## 📞 Support & Community
|
||||
|
||||
- **Documentation**: Complete guides at [claude-mem.ai/docs](https://claude-mem.ai/docs)
|
||||
- **Issues**: Report bugs at [GitHub Issues](https://github.com/thedotmack/claude-mem/issues)
|
||||
- **Feature Requests**: [GitHub Discussions](https://github.com/thedotmack/claude-mem/discussions)
|
||||
- **Community**: Join our [Discord](https://discord.gg/claude-mem) for tips and discussions
|
||||
|
||||
## 📄 License
|
||||
|
||||
This software is free to use but is NOT open source. See [LICENSE](LICENSE) file for complete terms.
|
||||
Licensed under AGPL-3.0. See `LICENSE`.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Ready to Transform Your Claude Code Experience?
|
||||
## Ready to remember more and repeat less?
|
||||
|
||||
```bash
|
||||
npm install -g claude-mem
|
||||
claude-mem install
|
||||
```
|
||||
|
||||
**Your AI assistant is about to get a lot smarter.** 🧠✨
|
||||
|
||||
---
|
||||
|
||||
*Built with ❤️ for developers who believe AI assistants should remember and learn from every conversation.*
|
||||
Your future self will thank you. 🧠✨
|
||||
-40
@@ -1,40 +0,0 @@
|
||||
# Claude Mem v3.3.8
|
||||
|
||||
## 🚀 Installation
|
||||
|
||||
### Quick Install (Recommended)
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/thedotmack/claude-mem/main/install.sh | bash
|
||||
```
|
||||
|
||||
### Manual Download
|
||||
Download the appropriate binary for your platform from the [releases page](https://github.com/thedotmack/claude-mem/releases/latest):
|
||||
|
||||
- **Windows x64**: `claude-mem.exe`
|
||||
- **Linux x64**: `claude-mem-linux`
|
||||
- **Linux ARM64**: `claude-mem-linux-arm64`
|
||||
- **macOS ARM64** (Apple Silicon): `claude-mem-macos-arm64`
|
||||
- **macOS x64** (Intel): `claude-mem-macos-x64`
|
||||
|
||||
## 📦 What's Included
|
||||
|
||||
- Multi-platform binaries for Windows, Linux, and macOS
|
||||
- Hook system for customization
|
||||
- Full documentation
|
||||
- MCP server integration for Claude Code
|
||||
|
||||
## 🔧 Supported Platforms
|
||||
|
||||
| Platform | Architecture | Binary Name |
|
||||
|----------|--------------|-------------|
|
||||
| Windows | x64 | claude-mem.exe |
|
||||
| Linux | x64 | claude-mem-linux |
|
||||
| Linux | ARM64 | claude-mem-linux-arm64 |
|
||||
| macOS | ARM64 (Apple Silicon) | claude-mem-macos-arm64 |
|
||||
| macOS | x64 (Intel) | claude-mem-macos-x64 |
|
||||
|
||||
## 📝 License
|
||||
|
||||
Binary distribution under proprietary license (free to use).
|
||||
Hook files under MIT license (open source).
|
||||
See LICENSE file for details.
|
||||
@@ -0,0 +1,23 @@
|
||||
---
|
||||
argument-hint: help | save [message] | remember [context] | (no args for help)
|
||||
description: Manage claude-mem operations and memory context
|
||||
allowed-tools: Bash(claude-mem:*), Bash(echo:*), Bash(cat:*)
|
||||
---
|
||||
|
||||
## Claude-Mem Command Handler
|
||||
|
||||
### Check for help command first
|
||||
!`[ -z "$ARGUMENTS" ] || [ "$ARGUMENTS" = "help" ] && printf '%s\n' '## 🧠 Claude-Mem Help' '' '**Available Commands:**' '' '• /claude-mem save [message] - Quick save of conversation overview' '• /claude-mem remember [query] - Search saved memories' '• /claude-mem help - Show this help' '' '**Quick Shortcuts:**' '• /save - Direct save' '• /remember - Direct search' '' '**About /save:**' 'Quick way to save an overview to claude-mem without processing the' 'entire transcript. Use this when you dont need a detailed archive,' 'just a summary of key points and decisions.' '' '**Optional Features (configure during install):**' '• Compress on /clear: Archives full transcript when clearing (off by default)' '• Session start: Loads recent memories when starting Claude Code' '' 'For more details: claude-mem --help' && exit 0`
|
||||
|
||||
### Process other commands
|
||||
Handle claude-mem operation: $ARGUMENTS
|
||||
|
||||
If $ARGUMENTS starts with "save":
|
||||
- Write an overview of the current conversation context
|
||||
- Add it to claude-mem using the chroma MCP tools
|
||||
- Save the overview using: `claude-mem save "your overview message"`
|
||||
|
||||
If $ARGUMENTS starts with "remember":
|
||||
- Search claude-mem for relevant memories using the query
|
||||
- Display the most relevant memories from previous sessions
|
||||
- Use chroma_query_documents to find and present context
|
||||
@@ -0,0 +1 @@
|
||||
Search claude-mem for #$ARGUMENTS and look up relevant context to help clarify what we are working on.
|
||||
@@ -0,0 +1,7 @@
|
||||
---
|
||||
allowed-tools: Bash
|
||||
description: Write an overview and save with claude-mem
|
||||
---
|
||||
**Write an overview** of the current conversation context and:
|
||||
1. **Add it to claude-mem** using the chroma MCP tools. Always use primitive types (strings, numbers, booleans) when calling MCP Chroma tools directly. Arrays should be comma-separated strings, and nested objects should be flattened.
|
||||
2. **Save the overview to index** using the claude-mem CLI tool: `claude-mem save "your overview message"`
|
||||
+513
File diff suppressed because one or more lines are too long
@@ -1,96 +0,0 @@
|
||||
# Multi-Platform Build Guide
|
||||
|
||||
This project now supports building binaries for multiple platforms using Bun's cross-compilation capabilities.
|
||||
|
||||
## Supported Platforms
|
||||
|
||||
- **Windows x64**: `claude-mem.exe`
|
||||
- **Linux x64**: `claude-mem-linux`
|
||||
- **Linux ARM64**: `claude-mem-linux-arm64`
|
||||
- **macOS ARM64**: `claude-mem-macos-arm64`
|
||||
- **macOS x64**: `claude-mem-macos-x64`
|
||||
|
||||
## Building
|
||||
|
||||
### Build All Platforms
|
||||
|
||||
To build binaries for all supported platforms:
|
||||
|
||||
```bash
|
||||
npm run build:multiplatform
|
||||
```
|
||||
|
||||
This will create binaries in the `releases/binaries/` directory.
|
||||
|
||||
### Build for NPM Package
|
||||
|
||||
To build a complete npm package with all platform binaries:
|
||||
|
||||
```bash
|
||||
npm run publish
|
||||
```
|
||||
|
||||
This creates a package in `releases/npm-package/` that includes:
|
||||
- Platform detection wrapper script
|
||||
- All platform-specific binaries
|
||||
- Hooks and configuration files
|
||||
|
||||
## How Platform Detection Works
|
||||
|
||||
The npm package includes a Node.js wrapper script (`claude-mem`) that:
|
||||
|
||||
1. Detects the current platform using `process.platform` and `process.arch`
|
||||
2. Maps the platform to the appropriate binary filename
|
||||
3. Executes the correct binary with all command-line arguments
|
||||
|
||||
### Platform Mapping
|
||||
|
||||
| Platform | Architecture | Binary Filename |
|
||||
|----------|-------------|------------------|
|
||||
| Windows | x64 | `claude-mem.exe` |
|
||||
| Linux | x64 | `claude-mem-linux` |
|
||||
| Linux | arm64/aarch64 | `claude-mem-linux-arm64` |
|
||||
| macOS | arm64 | `claude-mem-macos-arm64` |
|
||||
| macOS | x64 | `claude-mem-macos-x64` |
|
||||
|
||||
## Usage
|
||||
|
||||
After installation via npm, users can run:
|
||||
|
||||
```bash
|
||||
npx claude-mem --help
|
||||
```
|
||||
|
||||
The wrapper will automatically select and execute the correct binary for their platform.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Unsupported Platform Error
|
||||
|
||||
If you see an "Unsupported platform" error, check that your platform/architecture combination is in the supported list above.
|
||||
|
||||
### Binary Not Found Error
|
||||
|
||||
This indicates the platform detection worked, but the expected binary file is missing from the package. This shouldn't happen with properly built packages.
|
||||
|
||||
## Development
|
||||
|
||||
### Adding New Platforms
|
||||
|
||||
To add support for new platforms:
|
||||
|
||||
1. Add the platform to the `PLATFORMS` array in `scripts/build-multiplatform.sh`
|
||||
2. Update the platform detection logic in `scripts/claude-mem-wrapper.js`
|
||||
3. Update this documentation
|
||||
|
||||
### Testing Binaries
|
||||
|
||||
Test that a specific binary works:
|
||||
|
||||
```bash
|
||||
# Test Linux binary
|
||||
./releases/binaries/claude-mem-linux --help
|
||||
|
||||
# Test Windows binary (on Windows or with Wine)
|
||||
./releases/binaries/claude-mem.exe --help
|
||||
```
|
||||
@@ -1,584 +0,0 @@
|
||||
Bun's bundler implements a `--compile` flag for generating a standalone binary from a TypeScript or JavaScript file.
|
||||
|
||||
{% codetabs %}
|
||||
|
||||
```bash
|
||||
$ bun build ./cli.ts --compile --outfile mycli
|
||||
```
|
||||
|
||||
```ts#cli.ts
|
||||
console.log("Hello world!");
|
||||
```
|
||||
|
||||
{% /codetabs %}
|
||||
|
||||
This bundles `cli.ts` into an executable that can be executed directly:
|
||||
|
||||
```
|
||||
$ ./mycli
|
||||
Hello world!
|
||||
```
|
||||
|
||||
All imported files and packages are bundled into the executable, along with a copy of the Bun runtime. All built-in Bun and Node.js APIs are supported.
|
||||
|
||||
## Cross-compile to other platforms
|
||||
|
||||
The `--target` flag lets you compile your standalone executable for a different operating system, architecture, or version of Bun than the machine you're running `bun build` on.
|
||||
|
||||
To build for Linux x64 (most servers):
|
||||
|
||||
```sh
|
||||
bun build --compile --target=bun-linux-x64 ./index.ts --outfile myapp
|
||||
|
||||
# To support CPUs from before 2013, use the baseline version (nehalem)
|
||||
bun build --compile --target=bun-linux-x64-baseline ./index.ts --outfile myapp
|
||||
|
||||
# To explicitly only support CPUs from 2013 and later, use the modern version (haswell)
|
||||
# modern is faster, but baseline is more compatible.
|
||||
bun build --compile --target=bun-linux-x64-modern ./index.ts --outfile myapp
|
||||
```
|
||||
|
||||
To build for Linux ARM64 (e.g. Graviton or Raspberry Pi):
|
||||
|
||||
```sh
|
||||
# Note: the default architecture is x64 if no architecture is specified.
|
||||
bun build --compile --target=bun-linux-arm64 ./index.ts --outfile myapp
|
||||
```
|
||||
|
||||
To build for Windows x64:
|
||||
|
||||
```sh
|
||||
bun build --compile --target=bun-windows-x64 ./path/to/my/app.ts --outfile myapp
|
||||
|
||||
# To support CPUs from before 2013, use the baseline version (nehalem)
|
||||
bun build --compile --target=bun-windows-x64-baseline ./path/to/my/app.ts --outfile myapp
|
||||
|
||||
# To explicitly only support CPUs from 2013 and later, use the modern version (haswell)
|
||||
bun build --compile --target=bun-windows-x64-modern ./path/to/my/app.ts --outfile myapp
|
||||
|
||||
# note: if no .exe extension is provided, Bun will automatically add it for Windows executables
|
||||
```
|
||||
|
||||
To build for macOS arm64:
|
||||
|
||||
```sh
|
||||
bun build --compile --target=bun-darwin-arm64 ./path/to/my/app.ts --outfile myapp
|
||||
```
|
||||
|
||||
To build for macOS x64:
|
||||
|
||||
```sh
|
||||
bun build --compile --target=bun-darwin-x64 ./path/to/my/app.ts --outfile myapp
|
||||
```
|
||||
|
||||
#### Supported targets
|
||||
|
||||
The order of the `--target` flag does not matter, as long as they're delimited by a `-`.
|
||||
|
||||
| --target | Operating System | Architecture | Modern | Baseline | Libc |
|
||||
| --------------------- | ---------------- | ------------ | ------ | -------- | ----- |
|
||||
| bun-linux-x64 | Linux | x64 | ✅ | ✅ | glibc |
|
||||
| bun-linux-arm64 | Linux | arm64 | ✅ | N/A | glibc |
|
||||
| bun-windows-x64 | Windows | x64 | ✅ | ✅ | - |
|
||||
| ~~bun-windows-arm64~~ | Windows | arm64 | ❌ | ❌ | - |
|
||||
| bun-darwin-x64 | macOS | x64 | ✅ | ✅ | - |
|
||||
| bun-darwin-arm64 | macOS | arm64 | ✅ | N/A | - |
|
||||
| bun-linux-x64-musl | Linux | x64 | ✅ | ✅ | musl |
|
||||
| bun-linux-arm64-musl | Linux | arm64 | ✅ | N/A | musl |
|
||||
|
||||
On x64 platforms, Bun uses SIMD optimizations which require a modern CPU supporting AVX2 instructions. The `-baseline` build of Bun is for older CPUs that don't support these optimizations. Normally, when you install Bun we automatically detect which version to use but this can be harder to do when cross-compiling since you might not know the target CPU. You usually don't need to worry about it on Darwin x64, but it is relevant for Windows x64 and Linux x64. If you or your users see `"Illegal instruction"` errors, you might need to use the baseline version.
|
||||
|
||||
## Build-time constants
|
||||
|
||||
Use the `--define` flag to inject build-time constants into your executable, such as version numbers, build timestamps, or configuration values:
|
||||
|
||||
```bash
|
||||
$ bun build --compile --define BUILD_VERSION='"1.2.3"' --define BUILD_TIME='"2024-01-15T10:30:00Z"' src/cli.ts --outfile mycli
|
||||
```
|
||||
|
||||
These constants are embedded directly into your compiled binary at build time, providing zero runtime overhead and enabling dead code elimination optimizations.
|
||||
|
||||
{% callout type="info" %}
|
||||
For comprehensive examples and advanced patterns, see the [Build-time constants guide](/guides/runtime/build-time-constants).
|
||||
{% /callout %}
|
||||
|
||||
## Deploying to production
|
||||
|
||||
Compiled executables reduce memory usage and improve Bun's start time.
|
||||
|
||||
Normally, Bun reads and transpiles JavaScript and TypeScript files on `import` and `require`. This is part of what makes so much of Bun "just work", but it's not free. It costs time and memory to read files from disk, resolve file paths, parse, transpile, and print source code.
|
||||
|
||||
With compiled executables, you can move that cost from runtime to build-time.
|
||||
|
||||
When deploying to production, we recommend the following:
|
||||
|
||||
```sh
|
||||
bun build --compile --minify --sourcemap ./path/to/my/app.ts --outfile myapp
|
||||
```
|
||||
|
||||
### Bytecode compilation
|
||||
|
||||
To improve startup time, enable bytecode compilation:
|
||||
|
||||
```sh
|
||||
bun build --compile --minify --sourcemap --bytecode ./path/to/my/app.ts --outfile myapp
|
||||
```
|
||||
|
||||
Using bytecode compilation, `tsc` starts 2x faster:
|
||||
|
||||
{% image src="https://github.com/user-attachments/assets/dc8913db-01d2-48f8-a8ef-ac4e984f9763" width="689" /%}
|
||||
|
||||
Bytecode compilation moves parsing overhead for large input files from runtime to bundle time. Your app starts faster, in exchange for making the `bun build` command a little slower. It doesn't obscure source code.
|
||||
|
||||
**Experimental:** Bytecode compilation is an experimental feature introduced in Bun v1.1.30. Only `cjs` format is supported (which means no top-level-await). Let us know if you run into any issues!
|
||||
|
||||
### What do these flags do?
|
||||
|
||||
The `--minify` argument optimizes the size of the transpiled output code. If you have a large application, this can save megabytes of space. For smaller applications, it might still improve start time a little.
|
||||
|
||||
The `--sourcemap` argument embeds a sourcemap compressed with zstd, so that errors & stacktraces point to their original locations instead of the transpiled location. Bun will automatically decompress & resolve the sourcemap when an error occurs.
|
||||
|
||||
The `--bytecode` argument enables bytecode compilation. Every time you run JavaScript code in Bun, JavaScriptCore (the engine) will compile your source code into bytecode. We can move this parsing work from runtime to bundle time, saving you startup time.
|
||||
|
||||
## Act as the Bun CLI
|
||||
|
||||
{% note %}
|
||||
|
||||
New in Bun v1.2.16
|
||||
|
||||
{% /note %}
|
||||
|
||||
You can run a standalone executable as if it were the `bun` CLI itself by setting the `BUN_BE_BUN=1` environment variable. When this variable is set, the executable will ignore its bundled entrypoint and instead expose all the features of Bun's CLI.
|
||||
|
||||
For example, consider an executable compiled from a simple script:
|
||||
|
||||
```sh
|
||||
$ cat such-bun.js
|
||||
console.log("you shouldn't see this");
|
||||
|
||||
$ bun build --compile ./such-bun.js
|
||||
[3ms] bundle 1 modules
|
||||
[89ms] compile such-bun
|
||||
```
|
||||
|
||||
Normally, running `./such-bun` with arguments would execute the script. However, with the `BUN_BE_BUN=1` environment variable, it acts just like the `bun` binary:
|
||||
|
||||
```sh
|
||||
# Executable runs its own entrypoint by default
|
||||
$ ./such-bun install
|
||||
you shouldn't see this
|
||||
|
||||
# With the env var, the executable acts like the `bun` CLI
|
||||
$ BUN_BE_BUN=1 ./such-bun install
|
||||
bun install v1.2.16-canary.1 (1d1db811)
|
||||
Checked 63 installs across 64 packages (no changes) [5.00ms]
|
||||
```
|
||||
|
||||
This is useful for building CLI tools on top of Bun that may need to install packages, bundle dependencies, run different or local files and more without needing to download a separate binary or install bun.
|
||||
|
||||
## Full-stack executables
|
||||
|
||||
{% note %}
|
||||
|
||||
New in Bun v1.2.17
|
||||
|
||||
{% /note %}
|
||||
|
||||
Bun's `--compile` flag can create standalone executables that contain both server and client code, making it ideal for full-stack applications. When you import an HTML file in your server code, Bun automatically bundles all frontend assets (JavaScript, CSS, etc.) and embeds them into the executable. When Bun sees the HTML import on the server, it kicks off a frontend build process to bundle JavaScript, CSS, and other assets.
|
||||
|
||||
{% codetabs %}
|
||||
|
||||
```ts#server.ts
|
||||
import { serve } from "bun";
|
||||
import index from "./index.html";
|
||||
|
||||
const server = serve({
|
||||
routes: {
|
||||
"/": index,
|
||||
"/api/hello": { GET: () => Response.json({ message: "Hello from API" }) },
|
||||
},
|
||||
});
|
||||
|
||||
console.log(`Server running at http://localhost:${server.port}`);
|
||||
```
|
||||
|
||||
```html#index.html
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<title>My App</title>
|
||||
<link rel="stylesheet" href="./styles.css">
|
||||
</head>
|
||||
<body>
|
||||
<h1>Hello World</h1>
|
||||
<script src="./app.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
```js#app.js
|
||||
console.log("Hello from the client!");
|
||||
```
|
||||
|
||||
```css#styles.css
|
||||
body {
|
||||
background-color: #f0f0f0;
|
||||
}
|
||||
```
|
||||
|
||||
{% /codetabs %}
|
||||
|
||||
To build this into a single executable:
|
||||
|
||||
```sh
|
||||
bun build --compile ./server.ts --outfile myapp
|
||||
```
|
||||
|
||||
This creates a self-contained binary that includes:
|
||||
|
||||
- Your server code
|
||||
- The Bun runtime
|
||||
- All frontend assets (HTML, CSS, JavaScript)
|
||||
- Any npm packages used by your server
|
||||
|
||||
The result is a single file that can be deployed anywhere without needing Node.js, Bun, or any dependencies installed. Just run:
|
||||
|
||||
```sh
|
||||
./myapp
|
||||
```
|
||||
|
||||
Bun automatically handles serving the frontend assets with proper MIME types and cache headers. The HTML import is replaced with a manifest object that `Bun.serve` uses to efficiently serve pre-bundled assets.
|
||||
|
||||
For more details on building full-stack applications with Bun, see the [full-stack guide](/docs/bundler/fullstack).
|
||||
|
||||
## Worker
|
||||
|
||||
To use workers in a standalone executable, add the worker's entrypoint to the CLI arguments:
|
||||
|
||||
```sh
|
||||
$ bun build --compile ./index.ts ./my-worker.ts --outfile myapp
|
||||
```
|
||||
|
||||
Then, reference the worker in your code:
|
||||
|
||||
```ts
|
||||
console.log("Hello from Bun!");
|
||||
|
||||
// Any of these will work:
|
||||
new Worker("./my-worker.ts");
|
||||
new Worker(new URL("./my-worker.ts", import.meta.url));
|
||||
new Worker(new URL("./my-worker.ts", import.meta.url).href);
|
||||
```
|
||||
|
||||
As of Bun v1.1.25, when you add multiple entrypoints to a standalone executable, they will be bundled separately into the executable.
|
||||
|
||||
In the future, we may automatically detect usages of statically-known paths in `new Worker(path)` and then bundle those into the executable, but for now, you'll need to add it to the shell command manually like the above example.
|
||||
|
||||
If you use a relative path to a file not included in the standalone executable, it will attempt to load that path from disk relative to the current working directory of the process (and then error if it doesn't exist).
|
||||
|
||||
## SQLite
|
||||
|
||||
You can use `bun:sqlite` imports with `bun build --compile`.
|
||||
|
||||
By default, the database is resolved relative to the current working directory of the process.
|
||||
|
||||
```js
|
||||
import db from "./my.db" with { type: "sqlite" };
|
||||
|
||||
console.log(db.query("select * from users LIMIT 1").get());
|
||||
```
|
||||
|
||||
That means if the executable is located at `/usr/bin/hello`, the user's terminal is located at `/home/me/Desktop`, it will look for `/home/me/Desktop/my.db`.
|
||||
|
||||
```
|
||||
$ cd /home/me/Desktop
|
||||
$ ./hello
|
||||
```
|
||||
|
||||
## Embed assets & files
|
||||
|
||||
Standalone executables support embedding files.
|
||||
|
||||
To embed files into an executable with `bun build --compile`, import the file in your code.
|
||||
|
||||
```ts
|
||||
// this becomes an internal file path
|
||||
import icon from "./icon.png" with { type: "file" };
|
||||
import { file } from "bun";
|
||||
|
||||
export default {
|
||||
fetch(req) {
|
||||
// Embedded files can be streamed from Response objects
|
||||
return new Response(file(icon));
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
Embedded files can be read using `Bun.file`'s functions or the Node.js `fs.readFile` function (in `"node:fs"`).
|
||||
|
||||
For example, to read the contents of the embedded file:
|
||||
|
||||
```js
|
||||
import icon from "./icon.png" with { type: "file" };
|
||||
import { file } from "bun";
|
||||
|
||||
const bytes = await file(icon).arrayBuffer();
|
||||
// await fs.promises.readFile(icon)
|
||||
// fs.readFileSync(icon)
|
||||
```
|
||||
|
||||
### Embed SQLite databases
|
||||
|
||||
If your application wants to embed a SQLite database, set `type: "sqlite"` in the import attribute and the `embed` attribute to `"true"`.
|
||||
|
||||
```js
|
||||
import myEmbeddedDb from "./my.db" with { type: "sqlite", embed: "true" };
|
||||
|
||||
console.log(myEmbeddedDb.query("select * from users LIMIT 1").get());
|
||||
```
|
||||
|
||||
This database is read-write, but all changes are lost when the executable exits (since it's stored in memory).
|
||||
|
||||
### Embed N-API Addons
|
||||
|
||||
As of Bun v1.0.23, you can embed `.node` files into executables.
|
||||
|
||||
```js
|
||||
const addon = require("./addon.node");
|
||||
|
||||
console.log(addon.hello());
|
||||
```
|
||||
|
||||
Unfortunately, if you're using `@mapbox/node-pre-gyp` or other similar tools, you'll need to make sure the `.node` file is directly required or it won't bundle correctly.
|
||||
|
||||
### Embed directories
|
||||
|
||||
To embed a directory with `bun build --compile`, use a shell glob in your `bun build` command:
|
||||
|
||||
```sh
|
||||
$ bun build --compile ./index.ts ./public/**/*.png
|
||||
```
|
||||
|
||||
Then, you can reference the files in your code:
|
||||
|
||||
```ts
|
||||
import icon from "./public/assets/icon.png" with { type: "file" };
|
||||
import { file } from "bun";
|
||||
|
||||
export default {
|
||||
fetch(req) {
|
||||
// Embedded files can be streamed from Response objects
|
||||
return new Response(file(icon));
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
This is honestly a workaround, and we expect to improve this in the future with a more direct API.
|
||||
|
||||
### Listing embedded files
|
||||
|
||||
To get a list of all embedded files, use `Bun.embeddedFiles`:
|
||||
|
||||
```js
|
||||
import "./icon.png" with { type: "file" };
|
||||
import { embeddedFiles } from "bun";
|
||||
|
||||
console.log(embeddedFiles[0].name); // `icon-${hash}.png`
|
||||
```
|
||||
|
||||
`Bun.embeddedFiles` returns an array of `Blob` objects which you can use to get the size, contents, and other properties of the files.
|
||||
|
||||
```ts
|
||||
embeddedFiles: Blob[]
|
||||
```
|
||||
|
||||
The list of embedded files excludes bundled source code like `.ts` and `.js` files.
|
||||
|
||||
#### Content hash
|
||||
|
||||
By default, embedded files have a content hash appended to their name. This is useful for situations where you want to serve the file from a URL or CDN and have fewer cache invalidation issues. But sometimes, this is unexpected and you might want the original name instead:
|
||||
|
||||
To disable the content hash, pass `--asset-naming` to `bun build --compile` like this:
|
||||
|
||||
```sh
|
||||
$ bun build --compile --asset-naming="[name].[ext]" ./index.ts
|
||||
```
|
||||
|
||||
## Minification
|
||||
|
||||
To trim down the size of the executable a little, pass `--minify` to `bun build --compile`. This uses Bun's minifier to reduce the code size. Overall though, Bun's binary is still way too big and we need to make it smaller.
|
||||
|
||||
## Using Bun.build() API
|
||||
|
||||
You can also generate standalone executables using the `Bun.build()` JavaScript API. This is useful when you need programmatic control over the build process.
|
||||
|
||||
### Basic usage
|
||||
|
||||
```js
|
||||
await Bun.build({
|
||||
entrypoints: ["./app.ts"],
|
||||
outdir: "./dist",
|
||||
compile: {
|
||||
target: "bun-windows-x64",
|
||||
outfile: "myapp.exe",
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
### Windows metadata with Bun.build()
|
||||
|
||||
When targeting Windows, you can specify metadata through the `windows` object:
|
||||
|
||||
```js
|
||||
await Bun.build({
|
||||
entrypoints: ["./app.ts"],
|
||||
outdir: "./dist",
|
||||
compile: {
|
||||
target: "bun-windows-x64",
|
||||
outfile: "myapp.exe",
|
||||
windows: {
|
||||
title: "My Application",
|
||||
publisher: "My Company Inc",
|
||||
version: "1.2.3.4",
|
||||
description: "A powerful application built with Bun",
|
||||
copyright: "© 2024 My Company Inc",
|
||||
hideConsole: false, // Set to true for GUI applications
|
||||
icon: "./icon.ico", // Path to icon file
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
### Cross-compilation with Bun.build()
|
||||
|
||||
You can cross-compile for different platforms:
|
||||
|
||||
```js
|
||||
// Build for multiple platforms
|
||||
const platforms = [
|
||||
{ target: "bun-windows-x64", outfile: "app-windows.exe" },
|
||||
{ target: "bun-linux-x64", outfile: "app-linux" },
|
||||
{ target: "bun-darwin-arm64", outfile: "app-macos" },
|
||||
];
|
||||
|
||||
for (const platform of platforms) {
|
||||
await Bun.build({
|
||||
entrypoints: ["./app.ts"],
|
||||
outdir: "./dist",
|
||||
compile: platform,
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## Windows-specific flags
|
||||
|
||||
When compiling a standalone executable for Windows, there are several platform-specific options that can be used to customize the generated `.exe` file:
|
||||
|
||||
### Visual customization
|
||||
|
||||
- `--windows-icon=path/to/icon.ico` - Set the executable file icon
|
||||
- `--windows-hide-console` - Disable the background terminal window (useful for GUI applications)
|
||||
|
||||
### Metadata customization
|
||||
|
||||
You can embed version information and other metadata into your Windows executable:
|
||||
|
||||
- `--windows-title <STR>` - Set the product name (appears in file properties)
|
||||
- `--windows-publisher <STR>` - Set the company name
|
||||
- `--windows-version <STR>` - Set the version number (e.g. "1.2.3.4")
|
||||
- `--windows-description <STR>` - Set the file description
|
||||
- `--windows-copyright <STR>` - Set the copyright information
|
||||
|
||||
#### Example with all metadata flags:
|
||||
|
||||
```sh
|
||||
bun build --compile ./app.ts \
|
||||
--outfile myapp.exe \
|
||||
--windows-title "My Application" \
|
||||
--windows-publisher "My Company Inc" \
|
||||
--windows-version "1.2.3.4" \
|
||||
--windows-description "A powerful application built with Bun" \
|
||||
--windows-copyright "© 2024 My Company Inc"
|
||||
```
|
||||
|
||||
This metadata will be visible in Windows Explorer when viewing the file properties:
|
||||
|
||||
1. Right-click the executable in Windows Explorer
|
||||
2. Select "Properties"
|
||||
3. Go to the "Details" tab
|
||||
|
||||
#### Version string format
|
||||
|
||||
The `--windows-version` flag accepts version strings in the following formats:
|
||||
|
||||
- `"1"` - Will be normalized to "1.0.0.0"
|
||||
- `"1.2"` - Will be normalized to "1.2.0.0"
|
||||
- `"1.2.3"` - Will be normalized to "1.2.3.0"
|
||||
- `"1.2.3.4"` - Full version format
|
||||
|
||||
Each version component must be a number between 0 and 65535.
|
||||
|
||||
{% callout %}
|
||||
|
||||
These flags currently cannot be used when cross-compiling because they depend on Windows APIs. They are only available when building on Windows itself.
|
||||
|
||||
{% /callout %}
|
||||
|
||||
## Code signing on macOS
|
||||
|
||||
To codesign a standalone executable on macOS (which fixes Gatekeeper warnings), use the `codesign` command.
|
||||
|
||||
```sh
|
||||
$ codesign --deep --force -vvvv --sign "XXXXXXXXXX" ./myapp
|
||||
```
|
||||
|
||||
We recommend including an `entitlements.plist` file with JIT permissions.
|
||||
|
||||
```xml#entitlements.plist
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||
<plist version="1.0">
|
||||
<dict>
|
||||
<key>com.apple.security.cs.allow-jit</key>
|
||||
<true/>
|
||||
<key>com.apple.security.cs.allow-unsigned-executable-memory</key>
|
||||
<true/>
|
||||
<key>com.apple.security.cs.disable-executable-page-protection</key>
|
||||
<true/>
|
||||
<key>com.apple.security.cs.allow-dyld-environment-variables</key>
|
||||
<true/>
|
||||
<key>com.apple.security.cs.disable-library-validation</key>
|
||||
<true/>
|
||||
</dict>
|
||||
</plist>
|
||||
```
|
||||
|
||||
To codesign with JIT support, pass the `--entitlements` flag to `codesign`.
|
||||
|
||||
```sh
|
||||
$ codesign --deep --force -vvvv --sign "XXXXXXXXXX" --entitlements entitlements.plist ./myapp
|
||||
```
|
||||
|
||||
After codesigning, verify the executable:
|
||||
|
||||
```sh
|
||||
$ codesign -vvv --verify ./myapp
|
||||
./myapp: valid on disk
|
||||
./myapp: satisfies its Designated Requirement
|
||||
```
|
||||
|
||||
{% callout %}
|
||||
|
||||
Codesign support requires Bun v1.2.4 or newer.
|
||||
|
||||
{% /callout %}
|
||||
|
||||
## Unsupported CLI arguments
|
||||
|
||||
Currently, the `--compile` flag can only accept a single entrypoint at a time and does not support the following flags:
|
||||
|
||||
- `--outdir` — use `outfile` instead.
|
||||
- `--splitting`
|
||||
- `--public-path`
|
||||
- `--target=node` or `--target=browser`
|
||||
- `--no-bundle` - we always bundle everything into the executable.
|
||||
@@ -1,99 +0,0 @@
|
||||
# Output styles
|
||||
|
||||
> Adapt Claude Code for uses beyond software engineering
|
||||
|
||||
Output styles allow you to use Claude Code as any type of agent while keeping
|
||||
its core capabilities, such as running local scripts, reading/writing files, and
|
||||
tracking TODOs.
|
||||
|
||||
## Built-in output styles
|
||||
|
||||
Claude Code's **Default** output style is the existing system prompt, designed
|
||||
to help you complete software engineering tasks efficiently.
|
||||
|
||||
There are two additional built-in output styles focused on teaching you the
|
||||
codebase and how Claude operates:
|
||||
|
||||
* **Explanatory**: Provides educational "Insights" in between helping you
|
||||
complete software engineering tasks. Helps you understand implementation
|
||||
choices and codebase patterns.
|
||||
|
||||
* **Learning**: Collaborative, learn-by-doing mode where Claude will not only
|
||||
share "Insights" while coding, but also ask you to contribute small, strategic
|
||||
pieces of code yourself. Claude Code will add `TODO(human)` markers in your
|
||||
code for you to implement.
|
||||
|
||||
## How output styles work
|
||||
|
||||
Output styles directly modify Claude Code's system prompt.
|
||||
|
||||
* Non-default output styles exclude instructions specific to code generation and
|
||||
efficient output normally built into Claude Code (such as responding concisely
|
||||
and verifying code with tests).
|
||||
* Instead, these output styles have their own custom instructions added to the
|
||||
system prompt.
|
||||
|
||||
## Change your output style
|
||||
|
||||
You can either:
|
||||
|
||||
* Run `/output-style` to access the menu and select your output style (this can
|
||||
also be accessed from the `/config` menu)
|
||||
|
||||
* Run `/output-style [style]`, such as `/output-style explanatory`, to directly
|
||||
switch to a style
|
||||
|
||||
These changes apply to the [local project level](/en/docs/claude-code/settings)
|
||||
and are saved in `.claude/settings.local.json`.
|
||||
|
||||
## Create a custom output style
|
||||
|
||||
To set up a new output style with Claude's help, run
|
||||
`/output-style:new I want an output style that ...`
|
||||
|
||||
By default, output styles created through `/output-style:new` are saved as
|
||||
markdown files at the user level in `~/.claude/output-styles` and can be used
|
||||
across projects. They have the following structure:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: My Custom Style
|
||||
description:
|
||||
A brief description of what this style does, to be displayed to the user
|
||||
---
|
||||
|
||||
# Custom Style Instructions
|
||||
|
||||
You are an interactive CLI tool that helps users with software engineering
|
||||
tasks. [Your custom instructions here...]
|
||||
|
||||
## Specific Behaviors
|
||||
|
||||
[Define how the assistant should behave in this style...]
|
||||
```
|
||||
|
||||
You can also create your own output style Markdown files and save them either at
|
||||
the user level (`~/.claude/output-styles`) or the project level
|
||||
(`.claude/output-styles`).
|
||||
|
||||
## Comparisons to related features
|
||||
|
||||
### Output Styles vs. CLAUDE.md vs. --append-system-prompt
|
||||
|
||||
Output styles completely “turn off” the parts of Claude Code’s default system
|
||||
prompt specific to software engineering. Neither CLAUDE.md nor
|
||||
`--append-system-prompt` edit Claude Code’s default system prompt. CLAUDE.md
|
||||
adds the contents as a user message *following* Claude Code’s default system
|
||||
prompt. `--append-system-prompt` appends the content to the system prompt.
|
||||
|
||||
### Output Styles vs. [Agents](/en/docs/claude-code/sub-agents)
|
||||
|
||||
Output styles directly affect the main agent loop and only affect the system
|
||||
prompt. Agents are invoked to handle specific tasks and can include additional
|
||||
settings like the model to use, the tools they have available, and some context
|
||||
about when to use the agent.
|
||||
|
||||
### Output Styles vs. [Custom Slash Commands](/en/docs/claude-code/slash-commands)
|
||||
|
||||
You can think of output styles as “stored system prompts” and custom slash
|
||||
commands as “stored prompts”.
|
||||
@@ -1,80 +0,0 @@
|
||||
### Project Memory Example
|
||||
|
||||
Claude's context window has limits - long conversations eventually get truncated, and chats don't persist between sessions. Using Chroma as an external memory store solves these limitations, allowing Claude to reference past conversations and maintain context across multiple sessions.
|
||||
|
||||
First, tell Claude to use Chroma for memory as part of the project setup:
|
||||
```
|
||||
Remember, you have access to Chroma tools.
|
||||
At any point if the user references previous chats or memory, check chroma for similar conversations.
|
||||
Try to use retrieved information where possible.
|
||||
```
|
||||
|
||||
This prompt instructs Claude to:
|
||||
- Proactively check Chroma when memory-related topics come up
|
||||
- Search for semantically similar past conversations
|
||||
- Incorporate relevant historical context into responses
|
||||
|
||||
To store the current conversation:
|
||||
|
||||
```
|
||||
Please chunk our conversation into small chunks and store it in Chroma for future reference.
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```
|
||||
can you chunk our entire conversation into small, embeddable text chunks (not the code, but describe it so you can recreate it if necessary). no longer than a couple lines each. then, add it to the chroma collection for this project.
|
||||
```
|
||||
|
||||
Claude will:
|
||||
1. Break the conversation into smaller chunks (typically 512-1024 tokens)
|
||||
- Chunking is necessary because:
|
||||
- Large texts are harder to search semantically
|
||||
- Smaller chunks help retrieve more precise context
|
||||
- It prevents token limits in future retrievals
|
||||
2. Generate embeddings for each chunk
|
||||
3. Add metadata like timestamps and detected topics
|
||||
4. Store everything in your Chroma collection
|
||||
|
||||
Later, you can access past conversations naturally:
|
||||
```
|
||||
What did we discuss previously about the authentication system?
|
||||
```
|
||||
|
||||
Claude will:
|
||||
1. Search Chroma for chunks semantically related to authentication
|
||||
2. Filter by timestamp metadata for last week's discussions
|
||||
3. Incorporate the relevant historical context into its response
|
||||
|
||||
This setup is particularly useful for:
|
||||
- Long-running projects where context gets lost
|
||||
- Teams where multiple people interact with Claude
|
||||
- Complex discussions that reference past decisions
|
||||
- Maintaining consistent context across multiple chat sessions
|
||||
|
||||
### Advanced Features
|
||||
|
||||
The Chroma MCP server supports:
|
||||
|
||||
- **Collection Management**: Create and organize separate collections for different projects
|
||||
- **Document Operations**: Add, update, or delete documents
|
||||
- **Search Capabilities**:
|
||||
- Vector similarity search
|
||||
- Keyword-based search
|
||||
- Metadata filtering
|
||||
- **Batch Processing**: Efficient handling of multiple operations
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If you encounter issues:
|
||||
|
||||
1. Verify your configuration file syntax
|
||||
2. Ensure all paths are absolute and valid
|
||||
3. Try using full paths for `uvx` with `which uvx` and using that path in the config
|
||||
4. Check the Claude logs (paths listed above)
|
||||
|
||||
## Resources
|
||||
|
||||
- [Model Context Protocol Documentation](https://modelcontextprotocol.io/introduction)
|
||||
- [Chroma MCP Server Documentation](https://github.com/chroma-core/chroma-mcp)
|
||||
- [Claude Desktop Guide](https://docs.anthropic.com/claude/docs/claude-desktop)
|
||||
@@ -1,92 +0,0 @@
|
||||
### Team Knowledge Base Example
|
||||
|
||||
Let's say your team maintains a knowledge base of customer support interactions. By storing these in Chroma Cloud, team members can use Claude to quickly access and learn from past support cases.
|
||||
|
||||
First, set up your shared knowledge base:
|
||||
|
||||
```python
|
||||
import chromadb
|
||||
from datetime import datetime
|
||||
|
||||
# Connect to Chroma Cloud
|
||||
client = chromadb.HttpClient(
|
||||
ssl=True,
|
||||
host='api.trychroma.com',
|
||||
tenant='your-tenant-id',
|
||||
database='support-kb',
|
||||
headers={
|
||||
'x-chroma-token': 'YOUR_API_KEY'
|
||||
}
|
||||
)
|
||||
|
||||
# Create a collection for support cases
|
||||
collection = client.create_collection("support_cases")
|
||||
|
||||
# Add some example support cases
|
||||
support_cases = [
|
||||
{
|
||||
"case": "Customer reported issues connecting their IoT devices to the dashboard.",
|
||||
"resolution": "Guided customer through firewall configuration and port forwarding setup.",
|
||||
"category": "connectivity",
|
||||
"date": "2024-03-15"
|
||||
},
|
||||
{
|
||||
"case": "User couldn't access admin features after recent update.",
|
||||
"resolution": "Discovered role permissions weren't migrated correctly. Applied fix and documented process.",
|
||||
"category": "permissions",
|
||||
"date": "2024-03-16"
|
||||
}
|
||||
]
|
||||
|
||||
# Add documents to collection
|
||||
collection.add(
|
||||
documents=[case["case"] + "\n" + case["resolution"] for case in support_cases],
|
||||
metadatas=[{
|
||||
"category": case["category"],
|
||||
"date": case["date"]
|
||||
} for case in support_cases],
|
||||
ids=[f"case_{i}" for i in range(len(support_cases))]
|
||||
)
|
||||
```
|
||||
|
||||
Now team members can use Claude to access this knowledge.
|
||||
|
||||
In your claude config, add the following:
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"chroma": {
|
||||
"command": "uvx",
|
||||
"args": [
|
||||
"chroma-mcp",
|
||||
"--client-type",
|
||||
"cloud",
|
||||
"--tenant",
|
||||
"your-tenant-id",
|
||||
"--database",
|
||||
"support-kb",
|
||||
"--api-key",
|
||||
"YOUR_API_KEY"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Now you can use the knowledge base in your chats:
|
||||
```
|
||||
Claude, I'm having trouble helping a customer with IoT device connectivity.
|
||||
Can you check our support knowledge base for similar cases and suggest a solution?
|
||||
```
|
||||
|
||||
Claude will:
|
||||
1. Search the shared knowledge base for relevant cases
|
||||
2. Consider the context and solutions from similar past issues
|
||||
3. Provide recommendations based on previous successful resolutions
|
||||
|
||||
This setup is particularly powerful because:
|
||||
- All support team members have access to the same knowledge base
|
||||
- Claude can learn from the entire team's experience
|
||||
- Solutions are standardized across the organization
|
||||
- New team members can quickly get up to speed on common issues
|
||||
|
||||
@@ -1,787 +0,0 @@
|
||||
# Hooks reference
|
||||
|
||||
> This page provides reference documentation for implementing hooks in Claude Code.
|
||||
|
||||
<Tip>
|
||||
For a quickstart guide with examples, see [Get started with Claude Code hooks](/en/docs/claude-code/hooks-guide).
|
||||
</Tip>
|
||||
|
||||
## Configuration
|
||||
|
||||
Claude Code hooks are configured in your [settings files](/en/docs/claude-code/settings):
|
||||
|
||||
* `~/.claude/settings.json` - User settings
|
||||
* `.claude/settings.json` - Project settings
|
||||
* `.claude/settings.local.json` - Local project settings (not committed)
|
||||
* Enterprise managed policy settings
|
||||
|
||||
### Structure
|
||||
|
||||
Hooks are organized by matchers, where each matcher can have multiple hooks:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"EventName": [
|
||||
{
|
||||
"matcher": "ToolPattern",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "your-command-here"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
* **matcher**: Pattern to match tool names, case-sensitive (only applicable for
|
||||
`PreToolUse` and `PostToolUse`)
|
||||
* Simple strings match exactly: `Write` matches only the Write tool
|
||||
* Supports regex: `Edit|Write` or `Notebook.*`
|
||||
* Use `*` to match all tools. You can also use empty string (`""`) or leave
|
||||
`matcher` blank.
|
||||
* **hooks**: Array of commands to execute when the pattern matches
|
||||
* `type`: Currently only `"command"` is supported
|
||||
* `command`: The bash command to execute (can use `$CLAUDE_PROJECT_DIR`
|
||||
environment variable)
|
||||
* `timeout`: (Optional) How long a command should run, in seconds, before
|
||||
canceling that specific command.
|
||||
|
||||
For events like `UserPromptSubmit`, `Notification`, `Stop`, and `SubagentStop`
|
||||
that don't use matchers, you can omit the matcher field:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"UserPromptSubmit": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "/path/to/prompt-validator.py"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Project-Specific Hook Scripts
|
||||
|
||||
You can use the environment variable `CLAUDE_PROJECT_DIR` (only available when
|
||||
Claude Code spawns the hook command) to reference scripts stored in your project,
|
||||
ensuring they work regardless of Claude's current directory:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Write|Edit",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/check-style.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Hook Events
|
||||
|
||||
### PreToolUse
|
||||
|
||||
Runs after Claude creates tool parameters and before processing the tool call.
|
||||
|
||||
**Common matchers:**
|
||||
|
||||
* `Task` - Subagent tasks (see [subagents documentation](/en/docs/claude-code/sub-agents))
|
||||
* `Bash` - Shell commands
|
||||
* `Glob` - File pattern matching
|
||||
* `Grep` - Content search
|
||||
* `Read` - File reading
|
||||
* `Edit`, `MultiEdit` - File editing
|
||||
* `Write` - File writing
|
||||
* `WebFetch`, `WebSearch` - Web operations
|
||||
|
||||
### PostToolUse
|
||||
|
||||
Runs immediately after a tool completes successfully.
|
||||
|
||||
Recognizes the same matcher values as PreToolUse.
|
||||
|
||||
### Notification
|
||||
|
||||
Runs when Claude Code sends notifications. Notifications are sent when:
|
||||
|
||||
1. Claude needs your permission to use a tool. Example: "Claude needs your
|
||||
permission to use Bash"
|
||||
2. The prompt input has been idle for at least 60 seconds. "Claude is waiting
|
||||
for your input"
|
||||
|
||||
### UserPromptSubmit
|
||||
|
||||
Runs when the user submits a prompt, before Claude processes it. This allows you
|
||||
to add additional context based on the prompt/conversation, validate prompts, or
|
||||
block certain types of prompts.
|
||||
|
||||
### Stop
|
||||
|
||||
Runs when the main Claude Code agent has finished responding. Does not run if
|
||||
the stoppage occurred due to a user interrupt.
|
||||
|
||||
### SubagentStop
|
||||
|
||||
Runs when a Claude Code subagent (Task tool call) has finished responding.
|
||||
|
||||
### SessionEnd
|
||||
|
||||
Runs when a Claude Code session ends. Useful for cleanup tasks, logging session
|
||||
statistics, or saving session state.
|
||||
|
||||
The `reason` field in the hook input will be one of:
|
||||
|
||||
* `clear` - Session cleared with /clear command
|
||||
* `logout` - User logged out
|
||||
* `prompt_input_exit` - User exited while prompt input was visible
|
||||
* `other` - Other exit reasons
|
||||
|
||||
### PreCompact
|
||||
|
||||
Runs before Claude Code is about to run a compact operation.
|
||||
|
||||
**Matchers:**
|
||||
|
||||
* `manual` - Invoked from `/compact`
|
||||
* `auto` - Invoked from auto-compact (due to full context window)
|
||||
|
||||
### SessionStart
|
||||
|
||||
Runs when Claude Code starts a new session or resumes an existing session (which
|
||||
currently does start a new session under the hood). Useful for loading in
|
||||
development context like existing issues or recent changes to your codebase.
|
||||
|
||||
**Matchers:**
|
||||
|
||||
* `startup` - Invoked from startup
|
||||
* `resume` - Invoked from `--resume`, `--continue`, or `/resume`
|
||||
* `clear` - Invoked from `/clear`
|
||||
|
||||
## Hook Input
|
||||
|
||||
Hooks receive JSON data via stdin containing session information and
|
||||
event-specific data:
|
||||
|
||||
```typescript
|
||||
{
|
||||
// Common fields
|
||||
session_id: string
|
||||
transcript_path: string // Path to conversation JSON
|
||||
cwd: string // The current working directory when the hook is invoked
|
||||
|
||||
// Event-specific fields
|
||||
hook_event_name: string
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
### PreToolUse Input
|
||||
|
||||
The exact schema for `tool_input` depends on the tool.
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "abc123",
|
||||
"transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
|
||||
"cwd": "/Users/...",
|
||||
"hook_event_name": "PreToolUse",
|
||||
"tool_name": "Write",
|
||||
"tool_input": {
|
||||
"file_path": "/path/to/file.txt",
|
||||
"content": "file content"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### PostToolUse Input
|
||||
|
||||
The exact schema for `tool_input` and `tool_response` depends on the tool.
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "abc123",
|
||||
"transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
|
||||
"cwd": "/Users/...",
|
||||
"hook_event_name": "PostToolUse",
|
||||
"tool_name": "Write",
|
||||
"tool_input": {
|
||||
"file_path": "/path/to/file.txt",
|
||||
"content": "file content"
|
||||
},
|
||||
"tool_response": {
|
||||
"filePath": "/path/to/file.txt",
|
||||
"success": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Notification Input
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "abc123",
|
||||
"transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
|
||||
"cwd": "/Users/...",
|
||||
"hook_event_name": "Notification",
|
||||
"message": "Task completed successfully"
|
||||
}
|
||||
```
|
||||
|
||||
### UserPromptSubmit Input
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "abc123",
|
||||
"transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
|
||||
"cwd": "/Users/...",
|
||||
"hook_event_name": "UserPromptSubmit",
|
||||
"prompt": "Write a function to calculate the factorial of a number"
|
||||
}
|
||||
```
|
||||
|
||||
### Stop and SubagentStop Input
|
||||
|
||||
`stop_hook_active` is true when Claude Code is already continuing as a result of
|
||||
a stop hook. Check this value or process the transcript to prevent Claude Code
|
||||
from running indefinitely.
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "abc123",
|
||||
"transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
|
||||
"hook_event_name": "Stop",
|
||||
"stop_hook_active": true
|
||||
}
|
||||
```
|
||||
|
||||
### PreCompact Input
|
||||
|
||||
For `manual`, `custom_instructions` comes from what the user passes into
|
||||
`/compact`. For `auto`, `custom_instructions` is empty.
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "abc123",
|
||||
"transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
|
||||
"hook_event_name": "PreCompact",
|
||||
"trigger": "manual",
|
||||
"custom_instructions": ""
|
||||
}
|
||||
```
|
||||
|
||||
### SessionStart Input
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "abc123",
|
||||
"transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
|
||||
"hook_event_name": "SessionStart",
|
||||
"source": "startup"
|
||||
}
|
||||
```
|
||||
|
||||
### SessionEnd Input
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "abc123",
|
||||
"transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
|
||||
"cwd": "/Users/...",
|
||||
"hook_event_name": "SessionEnd",
|
||||
"reason": "exit"
|
||||
}
|
||||
```
|
||||
|
||||
## Hook Output
|
||||
|
||||
There are two ways for hooks to return output back to Claude Code. The output
|
||||
communicates whether to block and any feedback that should be shown to Claude
|
||||
and the user.
|
||||
|
||||
### Simple: Exit Code
|
||||
|
||||
Hooks communicate status through exit codes, stdout, and stderr:
|
||||
|
||||
* **Exit code 0**: Success. `stdout` is shown to the user in transcript mode
|
||||
(CTRL-R), except for `UserPromptSubmit` and `SessionStart`, where stdout is
|
||||
added to the context.
|
||||
* **Exit code 2**: Blocking error. `stderr` is fed back to Claude to process
|
||||
automatically. See per-hook-event behavior below.
|
||||
* **Other exit codes**: Non-blocking error. `stderr` is shown to the user and
|
||||
execution continues.
|
||||
|
||||
<Warning>
|
||||
Reminder: Claude Code does not see stdout if the exit code is 0, except for
|
||||
the `UserPromptSubmit` hook where stdout is injected as context.
|
||||
</Warning>
|
||||
|
||||
#### Exit Code 2 Behavior
|
||||
|
||||
| Hook Event | Behavior |
|
||||
| ------------------ | ------------------------------------------------------------------ |
|
||||
| `PreToolUse` | Blocks the tool call, shows stderr to Claude |
|
||||
| `PostToolUse` | Shows stderr to Claude (tool already ran) |
|
||||
| `Notification` | N/A, shows stderr to user only |
|
||||
| `UserPromptSubmit` | Blocks prompt processing, erases prompt, shows stderr to user only |
|
||||
| `Stop` | Blocks stoppage, shows stderr to Claude |
|
||||
| `SubagentStop` | Blocks stoppage, shows stderr to Claude subagent |
|
||||
| `PreCompact` | N/A, shows stderr to user only |
|
||||
| `SessionStart` | N/A, shows stderr to user only |
|
||||
| `SessionEnd` | N/A, shows stderr to user only |
|
||||
|
||||
### Advanced: JSON Output
|
||||
|
||||
Hooks can return structured JSON in `stdout` for more sophisticated control:
|
||||
|
||||
#### Common JSON Fields
|
||||
|
||||
All hook types can include these optional fields:
|
||||
|
||||
```json
|
||||
{
|
||||
"continue": true, // Whether Claude should continue after hook execution (default: true)
|
||||
"stopReason": "string", // Message shown when continue is false
|
||||
|
||||
"suppressOutput": true, // Hide stdout from transcript mode (default: false)
|
||||
"systemMessage": "string" // Optional warning message shown to the user
|
||||
}
|
||||
```
|
||||
|
||||
If `continue` is false, Claude stops processing after the hooks run.
|
||||
|
||||
* For `PreToolUse`, this is different from `"permissionDecision": "deny"`, which
|
||||
only blocks a specific tool call and provides automatic feedback to Claude.
|
||||
* For `PostToolUse`, this is different from `"decision": "block"`, which
|
||||
provides automated feedback to Claude.
|
||||
* For `UserPromptSubmit`, this prevents the prompt from being processed.
|
||||
* For `Stop` and `SubagentStop`, this takes precedence over any
|
||||
`"decision": "block"` output.
|
||||
* In all cases, `"continue" = false` takes precedence over any
|
||||
`"decision": "block"` output.
|
||||
|
||||
`stopReason` accompanies `continue` with a reason shown to the user, not shown
|
||||
to Claude.
|
||||
|
||||
#### `PreToolUse` Decision Control
|
||||
|
||||
`PreToolUse` hooks can control whether a tool call proceeds.
|
||||
|
||||
* `"allow"` bypasses the permission system. `permissionDecisionReason` is shown
|
||||
to the user but not to Claude.
|
||||
* `"deny"` prevents the tool call from executing. `permissionDecisionReason` is
|
||||
shown to Claude.
|
||||
* `"ask"` asks the user to confirm the tool call in the UI.
|
||||
`permissionDecisionReason` is shown to the user but not to Claude.
|
||||
|
||||
```json
|
||||
{
|
||||
"hookSpecificOutput": {
|
||||
"hookEventName": "PreToolUse",
|
||||
"permissionDecision": "allow" | "deny" | "ask",
|
||||
"permissionDecisionReason": "My reason here"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<Note>
|
||||
The `decision` and `reason` fields are deprecated for PreToolUse hooks.
|
||||
Use `hookSpecificOutput.permissionDecision` and
|
||||
`hookSpecificOutput.permissionDecisionReason` instead. The deprecated fields
|
||||
`"approve"` and `"block"` map to `"allow"` and `"deny"` respectively.
|
||||
</Note>
|
||||
|
||||
#### `PostToolUse` Decision Control
|
||||
|
||||
`PostToolUse` hooks can provide feedback to Claude after tool execution.
|
||||
|
||||
* `"block"` automatically prompts Claude with `reason`.
|
||||
* `undefined` does nothing. `reason` is ignored.
|
||||
* `"hookSpecificOutput.additionalContext"` adds context for Claude to consider.
|
||||
|
||||
```json
|
||||
{
|
||||
"decision": "block" | undefined,
|
||||
"reason": "Explanation for decision",
|
||||
"hookSpecificOutput": {
|
||||
"hookEventName": "PostToolUse",
|
||||
"additionalContext": "Additional information for Claude"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### `UserPromptSubmit` Decision Control
|
||||
|
||||
`UserPromptSubmit` hooks can control whether a user prompt is processed.
|
||||
|
||||
* `"block"` prevents the prompt from being processed. The submitted prompt is
|
||||
erased from context. `"reason"` is shown to the user but not added to context.
|
||||
* `undefined` allows the prompt to proceed normally. `"reason"` is ignored.
|
||||
* `"hookSpecificOutput.additionalContext"` adds the string to the context if not
|
||||
blocked.
|
||||
|
||||
```json
|
||||
{
|
||||
"decision": "block" | undefined,
|
||||
"reason": "Explanation for decision",
|
||||
"hookSpecificOutput": {
|
||||
"hookEventName": "UserPromptSubmit",
|
||||
"additionalContext": "My additional context here"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### `Stop`/`SubagentStop` Decision Control
|
||||
|
||||
`Stop` and `SubagentStop` hooks can control whether Claude must continue.
|
||||
|
||||
* `"block"` prevents Claude from stopping. You must populate `reason` for Claude
|
||||
to know how to proceed.
|
||||
* `undefined` allows Claude to stop. `reason` is ignored.
|
||||
|
||||
```json
|
||||
{
|
||||
"decision": "block" | undefined,
|
||||
"reason": "Must be provided when Claude is blocked from stopping"
|
||||
}
|
||||
```
|
||||
|
||||
#### `SessionStart` Decision Control
|
||||
|
||||
`SessionStart` hooks allow you to load in context at the start of a session.
|
||||
|
||||
* `"hookSpecificOutput.additionalContext"` adds the string to the context.
|
||||
* Multiple hooks' `additionalContext` values are concatenated.
|
||||
|
||||
```json
|
||||
{
|
||||
"hookSpecificOutput": {
|
||||
"hookEventName": "SessionStart",
|
||||
"additionalContext": "My additional context here"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### `SessionEnd` Decision Control
|
||||
|
||||
`SessionEnd` hooks run when a session ends. They cannot block session termination
|
||||
but can perform cleanup tasks.
|
||||
|
||||
#### Exit Code Example: Bash Command Validation
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
import json
|
||||
import re
|
||||
import sys
|
||||
|
||||
# Define validation rules as a list of (regex pattern, message) tuples
|
||||
VALIDATION_RULES = [
|
||||
(
|
||||
r"\bgrep\b(?!.*\|)",
|
||||
"Use 'rg' (ripgrep) instead of 'grep' for better performance and features",
|
||||
),
|
||||
(
|
||||
r"\bfind\s+\S+\s+-name\b",
|
||||
"Use 'rg --files | rg pattern' or 'rg --files -g pattern' instead of 'find -name' for better performance",
|
||||
),
|
||||
]
|
||||
|
||||
|
||||
def validate_command(command: str) -> list[str]:
|
||||
issues = []
|
||||
for pattern, message in VALIDATION_RULES:
|
||||
if re.search(pattern, command):
|
||||
issues.append(message)
|
||||
return issues
|
||||
|
||||
|
||||
try:
|
||||
input_data = json.load(sys.stdin)
|
||||
except json.JSONDecodeError as e:
|
||||
print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
tool_name = input_data.get("tool_name", "")
|
||||
tool_input = input_data.get("tool_input", {})
|
||||
command = tool_input.get("command", "")
|
||||
|
||||
if tool_name != "Bash" or not command:
|
||||
sys.exit(1)
|
||||
|
||||
# Validate the command
|
||||
issues = validate_command(command)
|
||||
|
||||
if issues:
|
||||
for message in issues:
|
||||
print(f"• {message}", file=sys.stderr)
|
||||
# Exit code 2 blocks tool call and shows stderr to Claude
|
||||
sys.exit(2)
|
||||
```
|
||||
|
||||
#### JSON Output Example: UserPromptSubmit to Add Context and Validation
|
||||
|
||||
<Note>
|
||||
For `UserPromptSubmit` hooks, you can inject context using either method:
|
||||
|
||||
* Exit code 0 with stdout: Claude sees the context (special case for `UserPromptSubmit`)
|
||||
* JSON output: Provides more control over the behavior
|
||||
</Note>
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
import json
|
||||
import sys
|
||||
import re
|
||||
import datetime
|
||||
|
||||
# Load input from stdin
|
||||
try:
|
||||
input_data = json.load(sys.stdin)
|
||||
except json.JSONDecodeError as e:
|
||||
print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
prompt = input_data.get("prompt", "")
|
||||
|
||||
# Check for sensitive patterns
|
||||
sensitive_patterns = [
|
||||
(r"(?i)\b(password|secret|key|token)\s*[:=]", "Prompt contains potential secrets"),
|
||||
]
|
||||
|
||||
for pattern, message in sensitive_patterns:
|
||||
if re.search(pattern, prompt):
|
||||
# Use JSON output to block with a specific reason
|
||||
output = {
|
||||
"decision": "block",
|
||||
"reason": f"Security policy violation: {message}. Please rephrase your request without sensitive information."
|
||||
}
|
||||
print(json.dumps(output))
|
||||
sys.exit(0)
|
||||
|
||||
# Add current time to context
|
||||
context = f"Current time: {datetime.datetime.now()}"
|
||||
print(context)
|
||||
|
||||
"""
|
||||
The following is also equivalent:
|
||||
print(json.dumps({
|
||||
"hookSpecificOutput": {
|
||||
"hookEventName": "UserPromptSubmit",
|
||||
"additionalContext": context,
|
||||
},
|
||||
}))
|
||||
"""
|
||||
|
||||
# Allow the prompt to proceed with the additional context
|
||||
sys.exit(0)
|
||||
```
|
||||
|
||||
#### JSON Output Example: PreToolUse with Approval
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
import json
|
||||
import sys
|
||||
|
||||
# Load input from stdin
|
||||
try:
|
||||
input_data = json.load(sys.stdin)
|
||||
except json.JSONDecodeError as e:
|
||||
print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
tool_name = input_data.get("tool_name", "")
|
||||
tool_input = input_data.get("tool_input", {})
|
||||
|
||||
# Example: Auto-approve file reads for documentation files
|
||||
if tool_name == "Read":
|
||||
file_path = tool_input.get("file_path", "")
|
||||
if file_path.endswith((".md", ".mdx", ".txt", ".json")):
|
||||
# Use JSON output to auto-approve the tool call
|
||||
output = {
|
||||
"decision": "approve",
|
||||
"reason": "Documentation file auto-approved",
|
||||
"suppressOutput": True # Don't show in transcript mode
|
||||
}
|
||||
print(json.dumps(output))
|
||||
sys.exit(0)
|
||||
|
||||
# For other cases, let the normal permission flow proceed
|
||||
sys.exit(0)
|
||||
```
|
||||
|
||||
## Working with MCP Tools
|
||||
|
||||
Claude Code hooks work seamlessly with
|
||||
[Model Context Protocol (MCP) tools](/en/docs/claude-code/mcp). When MCP servers
|
||||
provide tools, they appear with a special naming pattern that you can match in
|
||||
your hooks.
|
||||
|
||||
### MCP Tool Naming
|
||||
|
||||
MCP tools follow the pattern `mcp__<server>__<tool>`, for example:
|
||||
|
||||
* `mcp__memory__create_entities` - Memory server's create entities tool
|
||||
* `mcp__filesystem__read_file` - Filesystem server's read file tool
|
||||
* `mcp__github__search_repositories` - GitHub server's search tool
|
||||
|
||||
### Configuring Hooks for MCP Tools
|
||||
|
||||
You can target specific MCP tools or entire MCP servers:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "mcp__memory__.*",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "echo 'Memory operation initiated' >> ~/mcp-operations.log"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"matcher": "mcp__.*__write.*",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "/home/user/scripts/validate-mcp-write.py"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
<Tip>
|
||||
For practical examples including code formatting, notifications, and file protection, see [More Examples](/en/docs/claude-code/hooks-guide#more-examples) in the get started guide.
|
||||
</Tip>
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Disclaimer
|
||||
|
||||
**USE AT YOUR OWN RISK**: Claude Code hooks execute arbitrary shell commands on
|
||||
your system automatically. By using hooks, you acknowledge that:
|
||||
|
||||
* You are solely responsible for the commands you configure
|
||||
* Hooks can modify, delete, or access any files your user account can access
|
||||
* Malicious or poorly written hooks can cause data loss or system damage
|
||||
* Anthropic provides no warranty and assumes no liability for any damages
|
||||
resulting from hook usage
|
||||
* You should thoroughly test hooks in a safe environment before production use
|
||||
|
||||
Always review and understand any hook commands before adding them to your
|
||||
configuration.
|
||||
|
||||
### Security Best Practices
|
||||
|
||||
Here are some key practices for writing more secure hooks:
|
||||
|
||||
1. **Validate and sanitize inputs** - Never trust input data blindly
|
||||
2. **Always quote shell variables** - Use `"$VAR"` not `$VAR`
|
||||
3. **Block path traversal** - Check for `..` in file paths
|
||||
4. **Use absolute paths** - Specify full paths for scripts (use
|
||||
`$CLAUDE_PROJECT_DIR` for the project path)
|
||||
5. **Skip sensitive files** - Avoid `.env`, `.git/`, keys, etc.
|
||||
|
||||
### Configuration Safety
|
||||
|
||||
Direct edits to hooks in settings files don't take effect immediately. Claude
|
||||
Code:
|
||||
|
||||
1. Captures a snapshot of hooks at startup
|
||||
2. Uses this snapshot throughout the session
|
||||
3. Warns if hooks are modified externally
|
||||
4. Requires review in `/hooks` menu for changes to apply
|
||||
|
||||
This prevents malicious hook modifications from affecting your current session.
|
||||
|
||||
## Hook Execution Details
|
||||
|
||||
* **Timeout**: 60-second execution limit by default, configurable per command.
|
||||
* A timeout for an individual command does not affect the other commands.
|
||||
* **Parallelization**: All matching hooks run in parallel
|
||||
* **Deduplication**: Multiple identical hook commands are deduplicated automatically
|
||||
* **Environment**: Runs in current directory with Claude Code's environment
|
||||
* The `CLAUDE_PROJECT_DIR` environment variable is available and contains the
|
||||
absolute path to the project root directory (where Claude Code was started)
|
||||
* **Input**: JSON via stdin
|
||||
* **Output**:
|
||||
* PreToolUse/PostToolUse/Stop/SubagentStop: Progress shown in transcript (Ctrl-R)
|
||||
* Notification/SessionEnd: Logged to debug only (`--debug`)
|
||||
* UserPromptSubmit/SessionStart: stdout added as context for Claude
|
||||
|
||||
## Debugging
|
||||
|
||||
### Basic Troubleshooting
|
||||
|
||||
If your hooks aren't working:
|
||||
|
||||
1. **Check configuration** - Run `/hooks` to see if your hook is registered
|
||||
2. **Verify syntax** - Ensure your JSON settings are valid
|
||||
3. **Test commands** - Run hook commands manually first
|
||||
4. **Check permissions** - Make sure scripts are executable
|
||||
5. **Review logs** - Use `claude --debug` to see hook execution details
|
||||
|
||||
Common issues:
|
||||
|
||||
* **Quotes not escaped** - Use `\"` inside JSON strings
|
||||
* **Wrong matcher** - Check tool names match exactly (case-sensitive)
|
||||
* **Command not found** - Use full paths for scripts
|
||||
|
||||
### Advanced Debugging
|
||||
|
||||
For complex hook issues:
|
||||
|
||||
1. **Inspect hook execution** - Use `claude --debug` to see detailed hook
|
||||
execution
|
||||
2. **Validate JSON schemas** - Test hook input/output with external tools
|
||||
3. **Check environment variables** - Verify Claude Code's environment is correct
|
||||
4. **Test edge cases** - Try hooks with unusual file paths or inputs
|
||||
5. **Monitor system resources** - Check for resource exhaustion during hook
|
||||
execution
|
||||
6. **Use structured logging** - Implement logging in your hook scripts
|
||||
|
||||
### Debug Output Example
|
||||
|
||||
Use `claude --debug` to see hook execution details:
|
||||
|
||||
```
|
||||
[DEBUG] Executing hooks for PostToolUse:Write
|
||||
[DEBUG] Getting matching hook commands for PostToolUse with query: Write
|
||||
[DEBUG] Found 1 hook matchers in settings
|
||||
[DEBUG] Matched 1 hooks for query "Write"
|
||||
[DEBUG] Found 1 hook commands to execute
|
||||
[DEBUG] Executing hook command: <Your command> with timeout 60000ms
|
||||
[DEBUG] Hook command completed with status 0: <Your stdout>
|
||||
```
|
||||
|
||||
Progress messages appear in transcript mode (Ctrl-R) showing:
|
||||
|
||||
* Which hook is running
|
||||
* Command being executed
|
||||
* Success/failure status
|
||||
* Output or error messages
|
||||
@@ -1,202 +0,0 @@
|
||||
# Status line configuration
|
||||
|
||||
> Create a custom status line for Claude Code to display contextual information
|
||||
|
||||
Make Claude Code your own with a custom status line that displays at the bottom of the Claude Code interface, similar to how terminal prompts (PS1) work in shells like Oh-my-zsh.
|
||||
|
||||
## Create a custom status line
|
||||
|
||||
You can either:
|
||||
|
||||
* Run `/statusline` to ask Claude Code to help you set up a custom status line. By default, it will try to reproduce your terminal's prompt, but you can provide additional instructions about the behavior you want to Claude Code, such as `/statusline show the model name in orange`
|
||||
|
||||
* Directly add a `statusLine` command to your `.claude/settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"statusLine": {
|
||||
"type": "command",
|
||||
"command": "~/.claude/statusline.sh",
|
||||
"padding": 0 // Optional: set to 0 to let status line go to edge
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## How it Works
|
||||
|
||||
* The status line is updated when the conversation messages update
|
||||
* Updates run at most every 300ms
|
||||
* The first line of stdout from your command becomes the status line text
|
||||
* ANSI color codes are supported for styling your status line
|
||||
* Claude Code passes contextual information about the current session (model, directories, etc.) as JSON to your script via stdin
|
||||
|
||||
## JSON Input Structure
|
||||
|
||||
Your status line command receives structured data via stdin in JSON format:
|
||||
|
||||
```json
|
||||
{
|
||||
"hook_event_name": "Status",
|
||||
"session_id": "abc123...",
|
||||
"transcript_path": "/path/to/transcript.json",
|
||||
"cwd": "/current/working/directory",
|
||||
"model": {
|
||||
"id": "claude-opus-4-1",
|
||||
"display_name": "Opus"
|
||||
},
|
||||
"workspace": {
|
||||
"current_dir": "/current/working/directory",
|
||||
"project_dir": "/original/project/directory"
|
||||
},
|
||||
"version": "1.0.80",
|
||||
"output_style": {
|
||||
"name": "default"
|
||||
},
|
||||
"cost": {
|
||||
"total_cost_usd": 0.01234,
|
||||
"total_duration_ms": 45000,
|
||||
"total_api_duration_ms": 2300,
|
||||
"total_lines_added": 156,
|
||||
"total_lines_removed": 23
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Example Scripts
|
||||
|
||||
### Simple Status Line
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Read JSON input from stdin
|
||||
input=$(cat)
|
||||
|
||||
# Extract values using jq
|
||||
MODEL_DISPLAY=$(echo "$input" | jq -r '.model.display_name')
|
||||
CURRENT_DIR=$(echo "$input" | jq -r '.workspace.current_dir')
|
||||
|
||||
echo "[$MODEL_DISPLAY] 📁 ${CURRENT_DIR##*/}"
|
||||
```
|
||||
|
||||
### Git-Aware Status Line
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Read JSON input from stdin
|
||||
input=$(cat)
|
||||
|
||||
# Extract values using jq
|
||||
MODEL_DISPLAY=$(echo "$input" | jq -r '.model.display_name')
|
||||
CURRENT_DIR=$(echo "$input" | jq -r '.workspace.current_dir')
|
||||
|
||||
# Show git branch if in a git repo
|
||||
GIT_BRANCH=""
|
||||
if git rev-parse --git-dir > /dev/null 2>&1; then
|
||||
BRANCH=$(git branch --show-current 2>/dev/null)
|
||||
if [ -n "$BRANCH" ]; then
|
||||
GIT_BRANCH=" | 🌿 $BRANCH"
|
||||
fi
|
||||
fi
|
||||
|
||||
echo "[$MODEL_DISPLAY] 📁 ${CURRENT_DIR##*/}$GIT_BRANCH"
|
||||
```
|
||||
|
||||
### Python Example
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
import json
|
||||
import sys
|
||||
import os
|
||||
|
||||
# Read JSON from stdin
|
||||
data = json.load(sys.stdin)
|
||||
|
||||
# Extract values
|
||||
model = data['model']['display_name']
|
||||
current_dir = os.path.basename(data['workspace']['current_dir'])
|
||||
|
||||
# Check for git branch
|
||||
git_branch = ""
|
||||
if os.path.exists('.git'):
|
||||
try:
|
||||
with open('.git/HEAD', 'r') as f:
|
||||
ref = f.read().strip()
|
||||
if ref.startswith('ref: refs/heads/'):
|
||||
git_branch = f" | 🌿 {ref.replace('ref: refs/heads/', '')}"
|
||||
except:
|
||||
pass
|
||||
|
||||
print(f"[{model}] 📁 {current_dir}{git_branch}")
|
||||
```
|
||||
|
||||
### Node.js Example
|
||||
|
||||
```javascript
|
||||
#!/usr/bin/env node
|
||||
|
||||
const fs = require('fs');
|
||||
const path = require('path');
|
||||
|
||||
// Read JSON from stdin
|
||||
let input = '';
|
||||
process.stdin.on('data', chunk => input += chunk);
|
||||
process.stdin.on('end', () => {
|
||||
const data = JSON.parse(input);
|
||||
|
||||
// Extract values
|
||||
const model = data.model.display_name;
|
||||
const currentDir = path.basename(data.workspace.current_dir);
|
||||
|
||||
// Check for git branch
|
||||
let gitBranch = '';
|
||||
try {
|
||||
const headContent = fs.readFileSync('.git/HEAD', 'utf8').trim();
|
||||
if (headContent.startsWith('ref: refs/heads/')) {
|
||||
gitBranch = ` | 🌿 ${headContent.replace('ref: refs/heads/', '')}`;
|
||||
}
|
||||
} catch (e) {
|
||||
// Not a git repo or can't read HEAD
|
||||
}
|
||||
|
||||
console.log(`[${model}] 📁 ${currentDir}${gitBranch}`);
|
||||
});
|
||||
```
|
||||
|
||||
### Helper Function Approach
|
||||
|
||||
For more complex bash scripts, you can create helper functions:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Read JSON input once
|
||||
input=$(cat)
|
||||
|
||||
# Helper functions for common extractions
|
||||
get_model_name() { echo "$input" | jq -r '.model.display_name'; }
|
||||
get_current_dir() { echo "$input" | jq -r '.workspace.current_dir'; }
|
||||
get_project_dir() { echo "$input" | jq -r '.workspace.project_dir'; }
|
||||
get_version() { echo "$input" | jq -r '.version'; }
|
||||
get_cost() { echo "$input" | jq -r '.cost.total_cost_usd'; }
|
||||
get_duration() { echo "$input" | jq -r '.cost.total_duration_ms'; }
|
||||
get_lines_added() { echo "$input" | jq -r '.cost.total_lines_added'; }
|
||||
get_lines_removed() { echo "$input" | jq -r '.cost.total_lines_removed'; }
|
||||
|
||||
# Use the helpers
|
||||
MODEL=$(get_model_name)
|
||||
DIR=$(get_current_dir)
|
||||
echo "[$MODEL] 📁 ${DIR##*/}"
|
||||
```
|
||||
|
||||
## Tips
|
||||
|
||||
* Keep your status line concise - it should fit on one line
|
||||
* Use emojis (if your terminal supports them) and colors to make information scannable
|
||||
* Use `jq` for JSON parsing in Bash (see examples above)
|
||||
* Test your script by running it manually with mock JSON input: `echo '{"model":{"display_name":"Test"},"workspace":{"current_dir":"/test"}}' | ./statusline.sh`
|
||||
* Consider caching expensive operations (like git status) if needed
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
* If your status line doesn't appear, check that your script is executable (`chmod +x`)
|
||||
* Ensure your script outputs to stdout (not stderr)
|
||||
@@ -1,173 +0,0 @@
|
||||
# Claude Code Hook Configuration Documentation
|
||||
|
||||
**LOCKED by @docs-agent | Change to 🔑 to allow @docs-agent edits**
|
||||
|
||||
## Official Documentation Reference
|
||||
|
||||
- **Source**: Claude Code Hooks API Documentation
|
||||
- **Version**: v2025
|
||||
- **Last Verified**: 2025-08-31
|
||||
- **Official URL**: https://docs.anthropic.com/en/docs/claude-code/hooks
|
||||
|
||||
## Hook Configuration Structure
|
||||
|
||||
### Two Categories of Hooks
|
||||
|
||||
Claude Code hooks are divided into two distinct categories with different configuration structures:
|
||||
|
||||
#### 1. Tool-Related Hooks
|
||||
These hooks are triggered in relation to tool usage and require a `matcher` field:
|
||||
- `PreToolUse`: Executed before a tool is invoked
|
||||
- `PostToolUse`: Executed after a tool completes
|
||||
|
||||
**Configuration Structure:**
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "Edit|MultiEdit|Write",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "/path/to/script.js",
|
||||
"timeout": 60000
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. Non-Tool Hooks
|
||||
These hooks are triggered by system events and **MUST NOT** have a `matcher` or `pattern` field:
|
||||
- `PreCompact`: Before conversation compaction
|
||||
- `SessionStart`: When a new session begins
|
||||
- `SessionEnd`: When a session ends
|
||||
- `UserPromptSubmit`: When user submits a prompt
|
||||
- `Notification`: For system notifications
|
||||
- `Stop`: When Claude is stopping
|
||||
- `SubagentStop`: When a subagent is stopping
|
||||
|
||||
**Configuration Structure:**
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"SessionStart": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "/path/to/script.js",
|
||||
"timeout": 30000
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Common Configuration Mistakes
|
||||
|
||||
### ❌ INCORRECT: Adding `pattern` field to non-tool hooks
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreCompact": [
|
||||
{
|
||||
"pattern": "*", // WRONG: Non-tool hooks don't use patterns
|
||||
"hooks": [...]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### ✅ CORRECT: Non-tool hooks without matcher
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreCompact": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "/path/to/pre-compact.js",
|
||||
"timeout": 180000
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Hook Field Reference
|
||||
|
||||
### Common Fields (All Hooks)
|
||||
- `type`: Always `"command"` for external scripts
|
||||
- `command`: Absolute path to the executable script
|
||||
- `timeout`: Optional timeout in milliseconds (default: 60000)
|
||||
|
||||
### Tool Hook Specific
|
||||
- `matcher`: Regex pattern to match tool names
|
||||
- Example: `"Edit|MultiEdit|Write"`
|
||||
- Example: `"mcp__.*__write.*"`
|
||||
- Example: `"Bash"`
|
||||
|
||||
### Environment Variables Available to Hooks
|
||||
- `$CLAUDE_PROJECT_DIR`: Project root directory
|
||||
- Standard environment variables from the shell
|
||||
|
||||
## Hook Input/Output
|
||||
|
||||
### Input (via stdin)
|
||||
All hooks receive JSON input with common fields:
|
||||
```json
|
||||
{
|
||||
"session_id": "string",
|
||||
"transcript_path": "string",
|
||||
"cwd": "string",
|
||||
"hook_event_name": "string",
|
||||
// Additional event-specific fields
|
||||
}
|
||||
```
|
||||
|
||||
### Output Options
|
||||
Hooks can output:
|
||||
1. **Plain text** (stdout): Added as context
|
||||
2. **JSON** (stdout): Structured response for decisions
|
||||
3. **Exit codes**:
|
||||
- `0`: Success, continue normally
|
||||
- `1`: General error
|
||||
- `2`: Block operation (for PreToolUse)
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
### File Locations
|
||||
- User settings: `~/.claude/settings.json`
|
||||
- Project settings: `./.claude/settings.json`
|
||||
- Local settings: `./.claude/settings.local.json`
|
||||
|
||||
### Settings Precedence (Highest to Lowest)
|
||||
1. Enterprise managed policies
|
||||
2. Command line arguments
|
||||
3. Local project settings
|
||||
4. Shared project settings
|
||||
5. User settings
|
||||
|
||||
## Cross-References
|
||||
|
||||
- Code Implementation: `/Users/alexnewman/Scripts/claude-mem/src/commands/install.ts:263-320`
|
||||
- Hook Files: `/Users/alexnewman/Scripts/claude-mem/hooks/`
|
||||
- User Guide: `/Users/alexnewman/Scripts/claude-mem/README-npm.md`
|
||||
|
||||
## Version History
|
||||
|
||||
- **2025-08-31**: Fixed hook configuration to remove incorrect `pattern` field from non-tool hooks
|
||||
- **2025-08-31**: Documented official hook structure requirements per Claude Code API
|
||||
|
||||
---
|
||||
*This documentation is maintained by @docs-agent and verified against official Anthropic documentation.*
|
||||
@@ -1,127 +0,0 @@
|
||||
# Claude Code Hook Response Format Documentation
|
||||
## Source: Official Claude Code Docs v2025
|
||||
## Last Verified: 2025-08-31
|
||||
|
||||
## Common Hook Response Fields
|
||||
|
||||
All hooks can return these common fields:
|
||||
|
||||
```json
|
||||
{
|
||||
"continue": true, // Whether Claude should continue (default: true)
|
||||
"stopReason": "string", // Message shown when continue is false
|
||||
"suppressOutput": true, // Hide stdout from transcript (default: false)
|
||||
"systemMessage": "string" // Optional warning message shown to user
|
||||
}
|
||||
```
|
||||
|
||||
## Hook-Specific Response Formats
|
||||
|
||||
### PreCompact Hook
|
||||
**IMPORTANT**: PreCompact does NOT support `hookSpecificOutput`
|
||||
|
||||
```json
|
||||
{
|
||||
"continue": true,
|
||||
"suppressOutput": true
|
||||
}
|
||||
```
|
||||
|
||||
### SessionStart Hook
|
||||
SessionStart DOES support `hookSpecificOutput`:
|
||||
|
||||
```json
|
||||
{
|
||||
"continue": true,
|
||||
"hookSpecificOutput": {
|
||||
"hookEventName": "SessionStart",
|
||||
"additionalContext": "Context string to add to session"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### PreToolUse Hook
|
||||
```json
|
||||
{
|
||||
"continue": true,
|
||||
"hookSpecificOutput": {
|
||||
"hookEventName": "PreToolUse",
|
||||
"permissionDecision": "allow" | "deny" | "ask",
|
||||
"permissionDecisionReason": "Reason for decision"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### PostToolUse Hook
|
||||
```json
|
||||
{
|
||||
"decision": "block", // Optional - blocks further processing
|
||||
"reason": "Explanation",
|
||||
"hookSpecificOutput": {
|
||||
"hookEventName": "PostToolUse",
|
||||
"additionalContext": "Additional information for Claude"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### UserPromptSubmit Hook
|
||||
```json
|
||||
{
|
||||
"decision": "block", // Optional - blocks the prompt
|
||||
"reason": "Security policy violation",
|
||||
"hookSpecificOutput": {
|
||||
"hookEventName": "UserPromptSubmit",
|
||||
"additionalContext": "Additional context for the prompt"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Exit Codes
|
||||
|
||||
- `0`: Success - hook executed successfully
|
||||
- `1`: Error - shown to user with stdout
|
||||
- `2`: Error - shown to Claude with stderr
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
### \u274c INCORRECT: Using wrong field names
|
||||
```javascript
|
||||
// WRONG
|
||||
{
|
||||
"decision": "block", // \u274c Wrong field
|
||||
"reason": "Error message" // \u274c Wrong field
|
||||
}
|
||||
```
|
||||
|
||||
### \u2705 CORRECT: Using official field names
|
||||
```javascript
|
||||
// RIGHT
|
||||
{
|
||||
"continue": false,
|
||||
"stopReason": "Error message"
|
||||
}
|
||||
```
|
||||
|
||||
### \u274c INCORRECT: Adding hookSpecificOutput to PreCompact
|
||||
```javascript
|
||||
// WRONG - PreCompact doesn't support this
|
||||
{
|
||||
"hookSpecificOutput": {
|
||||
"hookEventName": "PreCompact",
|
||||
"status": "success"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### \u2705 CORRECT: Simple response for PreCompact
|
||||
```javascript
|
||||
// RIGHT
|
||||
{
|
||||
"continue": true,
|
||||
"suppressOutput": true
|
||||
}
|
||||
```
|
||||
|
||||
## References
|
||||
- Official Docs: https://docs.anthropic.com/en/docs/claude-code/hooks
|
||||
- Hook Examples: https://docs.anthropic.com/en/docs/claude-code/hooks-guide
|
||||
@@ -1,175 +0,0 @@
|
||||
# Claude Code Hooks Configuration Documentation
|
||||
## Source: Official Claude Code Docs v2025
|
||||
## Last Verified: 2025-08-31
|
||||
|
||||
## Hook Configuration Structure
|
||||
|
||||
### For Tool-Based Hooks (PreToolUse, PostToolUse)
|
||||
These hooks use the `matcher` field to match tool patterns:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "ToolPattern", // Required for tool hooks
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "your-command-here",
|
||||
"timeout": 60000 // Optional, in milliseconds
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### For Non-Tool Hooks (PreCompact, SessionStart, etc.)
|
||||
These hooks DO NOT use matcher/pattern fields:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreCompact": [
|
||||
{
|
||||
// NO matcher or pattern field!
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "/path/to/script.js",
|
||||
"timeout": 180000
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Available Hook Events
|
||||
|
||||
### Tool-Related Hooks (use matcher)
|
||||
- **PreToolUse**: Before tool execution
|
||||
- **PostToolUse**: After tool execution
|
||||
|
||||
### System Event Hooks (no matcher)
|
||||
- **PreCompact**: Before conversation compaction
|
||||
- **SessionStart**: When session begins
|
||||
- **SessionEnd**: When session ends (not in official docs)
|
||||
- **UserPromptSubmit**: When user submits prompt
|
||||
- **Notification**: When Claude needs user input
|
||||
- **Stop**: When stop is requested
|
||||
- **SubagentStop**: When subagent stop is requested
|
||||
|
||||
## Hook Payload Structure
|
||||
|
||||
### Common Fields (all hooks)
|
||||
```json
|
||||
{
|
||||
"session_id": "string",
|
||||
"transcript_path": "string",
|
||||
"hook_event_name": "string",
|
||||
"cwd": "string" // Current working directory
|
||||
}
|
||||
```
|
||||
|
||||
### PreCompact Specific
|
||||
```json
|
||||
{
|
||||
"hook_event_name": "PreCompact",
|
||||
"trigger": "manual" | "auto",
|
||||
"custom_instructions": "string"
|
||||
}
|
||||
```
|
||||
|
||||
### SessionStart Specific
|
||||
```json
|
||||
{
|
||||
"hook_event_name": "SessionStart",
|
||||
"source": "startup" | "compact" | "vscode" | "web"
|
||||
}
|
||||
```
|
||||
|
||||
### PreToolUse/PostToolUse Specific
|
||||
```json
|
||||
{
|
||||
"tool_name": "string",
|
||||
"tool_input": { /* tool specific */ },
|
||||
"tool_response": { /* PostToolUse only */ }
|
||||
}
|
||||
```
|
||||
|
||||
## Common Configuration Mistakes
|
||||
|
||||
### \u274c INCORRECT: Using 'pattern' for non-tool hooks
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreCompact": [{
|
||||
"pattern": "*", // \u274c WRONG - non-tool hooks don't use this
|
||||
"hooks": [...]
|
||||
}]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### \u2705 CORRECT: No matcher for non-tool hooks
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreCompact": [{
|
||||
// No pattern or matcher field
|
||||
"hooks": [...]
|
||||
}]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### \u274c INCORRECT: Wrong matcher field name
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreToolUse": [{
|
||||
"pattern": "Bash", // \u274c WRONG field name
|
||||
"hooks": [...]
|
||||
}]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### \u2705 CORRECT: Using 'matcher' for tool hooks
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreToolUse": [{
|
||||
"matcher": "Bash", // \u2705 Correct field name
|
||||
"hooks": [...]
|
||||
}]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Matcher Patterns for Tool Hooks
|
||||
|
||||
- **Exact match**: `"Bash"` - matches only Bash tool
|
||||
- **Multiple tools**: `"Edit|MultiEdit|Write"` - matches any of these
|
||||
- **MCP tools**: `"mcp__memory__.*"` - matches all memory server tools
|
||||
- **All tools**: `"*"` - matches everything
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Hooks have access to:
|
||||
- `$CLAUDE_PROJECT_DIR` - Project root directory
|
||||
|
||||
## Settings File Locations
|
||||
|
||||
1. **User settings**: `~/.claude/settings.json`
|
||||
2. **Project settings**: `./.claude/settings.json`
|
||||
3. **Local settings**: `./.claude/settings.local.json`
|
||||
4. **Managed settings**: `/Library/Application Support/ClaudeCode/managed-settings.json`
|
||||
|
||||
## References
|
||||
- Official Docs: https://docs.anthropic.com/en/docs/claude-code/hooks
|
||||
- Hook Guide: https://docs.anthropic.com/en/docs/claude-code/hooks-guide
|
||||
@@ -1,133 +0,0 @@
|
||||
# MCP Configuration Documentation
|
||||
## Source: Official Claude Code Docs v2025
|
||||
## Last Verified: 2025-08-31
|
||||
|
||||
## MCP Configuration File Locations
|
||||
|
||||
### User Scope
|
||||
- **File**: `~/.claude.json`
|
||||
- **Purpose**: User-wide MCP servers available across all projects
|
||||
- **Persistence**: Persists across projects
|
||||
- **Example Path**: `/Users/username/.claude.json`
|
||||
|
||||
### Project Scope
|
||||
- **File**: `./.mcp.json`
|
||||
- **Purpose**: Project-specific servers for team collaboration
|
||||
- **Persistence**: Checked into version control
|
||||
- **Example Path**: `/path/to/project/.mcp.json`
|
||||
|
||||
### Local Scope
|
||||
- **Status**: Not officially documented
|
||||
- **Implementation**: Currently uses `~/.claude.json` (may need revision)
|
||||
|
||||
## Configuration Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"server-name": {
|
||||
"command": "command-to-run",
|
||||
"args": ["arg1", "arg2"],
|
||||
"env": {
|
||||
"ENV_VAR": "value"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Example Configurations
|
||||
|
||||
### Memory Server (stdio)
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"claude-mem": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-memory"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### HTTP Server
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"api-server": {
|
||||
"type": "sse",
|
||||
"url": "${API_BASE_URL:-https://api.example.com}/mcp",
|
||||
"headers": {
|
||||
"Authorization": "Bearer ${API_KEY}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Environment Variable Expansion
|
||||
|
||||
MCP configs support environment variable expansion:
|
||||
- `${VAR}` - Direct expansion
|
||||
- `${VAR:-default}` - With fallback value
|
||||
|
||||
Applicable fields:
|
||||
- `command`
|
||||
- `args`
|
||||
- `env`
|
||||
- `url`
|
||||
- `headers`
|
||||
|
||||
## CLI Commands
|
||||
|
||||
```bash
|
||||
# Add a server
|
||||
claude mcp add <name> <command> [args...]
|
||||
|
||||
# Add with scope
|
||||
claude mcp add <name> --scope project /path/to/server
|
||||
claude mcp add <name> --scope user /path/to/server
|
||||
|
||||
# List servers
|
||||
claude mcp list
|
||||
|
||||
# Get server details
|
||||
claude mcp get <name>
|
||||
|
||||
# Remove server
|
||||
claude mcp remove <name>
|
||||
|
||||
# Check status (within Claude Code)
|
||||
/mcp
|
||||
```
|
||||
|
||||
## Tool Naming Convention
|
||||
|
||||
MCP tools follow the pattern: `mcp__<serverName>__<toolName>`
|
||||
|
||||
Example:
|
||||
- Server: `claude-mem`
|
||||
- Tool: `create_entities`
|
||||
- Full name: `mcp__claude_mem__create_entities`
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Tool Permissions**: Must explicitly allow MCP tools via `--allowedTools`
|
||||
2. **Server Trust**: Only use MCP servers from trusted sources
|
||||
3. **Credential Management**: Use environment variables for sensitive data
|
||||
4. **Audit Trail**: MCP operations can be monitored via hooks
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Issue: MCP server not connecting
|
||||
**Solution**: Check that the command and args are correct, and npx is in PATH
|
||||
|
||||
### Issue: Tools not available
|
||||
**Solution**: Ensure server is in allowed list and properly configured
|
||||
|
||||
### Issue: Configuration not loading
|
||||
**Solution**: Verify JSON syntax and file location
|
||||
|
||||
## References
|
||||
- Official Docs: https://docs.anthropic.com/en/docs/claude-code/mcp
|
||||
- MCP Protocol: https://modelcontextprotocol.io/
|
||||
@@ -1,82 +0,0 @@
|
||||
# SessionStart Hook Documentation
|
||||
|
||||
## Official Documentation Reference
|
||||
- **Source**: https://docs.anthropic.com/en/docs/claude-code/hooks#sessionstart
|
||||
- **Last Verified**: 2025-08-31
|
||||
- **Version**: Claude Code v2025
|
||||
|
||||
## Hook Payload Structure
|
||||
|
||||
The SessionStart hook receives the following JSON payload via stdin:
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "string",
|
||||
"transcript_path": "string",
|
||||
"hook_event_name": "SessionStart",
|
||||
"source": "startup" | "compact" | "vscode" | "web"
|
||||
}
|
||||
```
|
||||
|
||||
### Field Descriptions
|
||||
|
||||
- **session_id**: Unique identifier for the Claude Code session
|
||||
- **transcript_path**: Path to the conversation transcript JSONL file
|
||||
- **hook_event_name**: Always "SessionStart" for this hook
|
||||
- **source**: Indicates how the session was initiated:
|
||||
- `"startup"`: New session started normally (should load context)
|
||||
- `"compact"`: Session started after compaction (may skip context)
|
||||
- `"vscode"`: Session initiated from VS Code extension
|
||||
- `"web"`: Session initiated from web interface
|
||||
|
||||
## Response Format
|
||||
|
||||
The hook should output JSON in the following format to add context:
|
||||
|
||||
```json
|
||||
{
|
||||
"hookSpecificOutput": {
|
||||
"hookEventName": "SessionStart",
|
||||
"additionalContext": "string"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Response Fields
|
||||
|
||||
- **hookSpecificOutput**: Container for hook-specific output
|
||||
- **hookEventName**: Must be "SessionStart"
|
||||
- **additionalContext**: String content to add to the session context
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
### Context Loading Strategy
|
||||
|
||||
The hook should determine whether to load context based on the `source` field:
|
||||
|
||||
1. **For "startup" source**: Load full context from memory
|
||||
2. **For "compact" source**: Skip or load minimal context (session continuing after compaction)
|
||||
3. **For "vscode"/"web" sources**: Load context as appropriate
|
||||
|
||||
### Error Handling
|
||||
|
||||
- If context loading fails, exit silently (exit code 0)
|
||||
- Do not break the session start with errors
|
||||
- Log errors to separate log file if needed
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
### Incorrect Field Check (FIXED)
|
||||
**Wrong**: Checking `payload.reason === 'continue'`
|
||||
**Correct**: Checking `payload.source === 'compact'`
|
||||
|
||||
The payload does not have a `reason` field. The `source` field indicates the session initiation context.
|
||||
|
||||
## Code Location
|
||||
- **File**: `/Users/alexnewman/Scripts/claude-mem/hooks/session-start.js`
|
||||
- **Line**: 53-66 (field check and documentation)
|
||||
|
||||
## Cross-References
|
||||
- General Hooks Documentation: [docs/claude-code/hooks.md](./hooks.md)
|
||||
- Hook Response Formats: [docs/claude-code/hook-responses.md](./hook-responses.md)
|
||||
- MCP Configuration: [docs/claude-code/mcp-configuration.md](./mcp-configuration.md)
|
||||
@@ -1,33 +0,0 @@
|
||||
<session-start-hook>
|
||||
|
||||
🧠 What's new: Thursday, September 4, 2025 at 06:13 PM EDT
|
||||
====================================================================
|
||||
Established Claude memory management infrastructure with compression tools for session archiving. Optimized session summary generation with compact command overviews for improved retrieval efficiency.
|
||||
|
||||
📚 Recent Context
|
||||
====================================================================
|
||||
👀 in claude_mem_source_d096f650-76a3-4163-9b7a-19f36a13c648_{number}:
|
||||
|
||||
1. Removed maxTurns:1 limitation that prevented Claude from completing multi-step compression with tool calls
|
||||
— maxTurns, Claude SDK, compression fix, MCP tools
|
||||
|
||||
3. Deployed steve-krug-ux agent to redesign prompt from pipe-separated to JSON with XMLResponse tags
|
||||
— steve-krug-ux, JSON format, prompt redesign
|
||||
|
||||
5. Expanded TranscriptCompressor to use all 13 claude-mem MCP tools for intelligent compression
|
||||
— allowedTools, MCP tools expansion, TranscriptCompressor
|
||||
|
||||
6. Traced index population failure through multiple system layers to identify root cause
|
||||
— debugging, ContextTemplates, claude-mem-index, trace
|
||||
|
||||
======================================================================
|
||||
👀 in claude_mem_source_d096f650-76a3-4163-9b7a-19f36a13c648_{number}:
|
||||
|
||||
1. Implemented Claude memory management and compression tools system
|
||||
— memory management, compression, archiving, session context
|
||||
|
||||
2. Generated compact command overview for session summaries
|
||||
— command overview, session summaries, memory retrieval
|
||||
|
||||
======================================================================
|
||||
</session-start-hook>
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,286 +0,0 @@
|
||||
# MCP TypeScript SDK Server Implementation Guide
|
||||
|
||||
## Documentation Source
|
||||
- **SDK Version**: @modelcontextprotocol/sdk v1.0.0
|
||||
- **Last Verified**: 2025-09-01
|
||||
- **Official Docs**: https://github.com/modelcontextprotocol/typescript-sdk
|
||||
|
||||
## Server Creation Patterns
|
||||
|
||||
### Low-Level Server vs McpServer
|
||||
|
||||
The SDK provides two approaches for creating MCP servers:
|
||||
|
||||
1. **Low-Level Server Class** (Used in claude-mem)
|
||||
- Direct control over request handling
|
||||
- Manual registration with `setRequestHandler`
|
||||
- More flexibility for custom routing logic
|
||||
|
||||
```typescript
|
||||
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
|
||||
|
||||
const server = new Server(
|
||||
{
|
||||
name: 'server-name',
|
||||
version: '1.0.0'
|
||||
},
|
||||
{
|
||||
capabilities: {
|
||||
tools: {} // Declare tool capability
|
||||
}
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
2. **High-Level McpServer Class** (Alternative approach)
|
||||
- Simplified API with `registerTool`, `registerResource`, `registerPrompt`
|
||||
- Automatic routing and validation
|
||||
- Less boilerplate code
|
||||
|
||||
```typescript
|
||||
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
||||
|
||||
const server = new McpServer({
|
||||
name: 'server-name',
|
||||
version: '1.0.0'
|
||||
});
|
||||
```
|
||||
|
||||
## Tool Handler Registration
|
||||
|
||||
### Pattern 1: Single Handler with CallToolRequestSchema (claude-mem approach)
|
||||
|
||||
```typescript
|
||||
import { CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
|
||||
|
||||
server.setRequestHandler(CallToolRequestSchema, async (request) => {
|
||||
const { name, arguments: args } = request.params;
|
||||
|
||||
// Validate arguments exist
|
||||
if (!args) {
|
||||
throw new Error(`No arguments provided for tool: ${name}`);
|
||||
}
|
||||
|
||||
// Route to specific tool implementation
|
||||
switch (name) {
|
||||
case 'tool-name':
|
||||
// Tool implementation
|
||||
return {
|
||||
content: [{
|
||||
type: 'text',
|
||||
text: 'Result'
|
||||
}]
|
||||
};
|
||||
default:
|
||||
throw new Error(`Unknown tool: ${name}`);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Pattern 2: Individual Tool Registration (McpServer approach)
|
||||
|
||||
```typescript
|
||||
server.registerTool(
|
||||
'tool-name',
|
||||
{
|
||||
title: 'Tool Title',
|
||||
description: 'Tool description',
|
||||
inputSchema: { param: z.string() }
|
||||
},
|
||||
async ({ param }) => ({
|
||||
content: [{
|
||||
type: 'text',
|
||||
text: `Result for ${param}`
|
||||
}]
|
||||
})
|
||||
);
|
||||
```
|
||||
|
||||
## Stdio Transport Usage
|
||||
|
||||
### Standard Pattern for CLI-based Servers
|
||||
|
||||
```typescript
|
||||
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
|
||||
|
||||
async function main() {
|
||||
// 1. Initialize backend services first
|
||||
await initializeBackend();
|
||||
|
||||
// 2. Create transport
|
||||
const transport = new StdioServerTransport();
|
||||
|
||||
// 3. Connect server to transport
|
||||
await server.connect(transport);
|
||||
|
||||
// 4. Log to stderr (stdout is for protocol)
|
||||
console.error('Server started on stdio');
|
||||
}
|
||||
```
|
||||
|
||||
### Key Points:
|
||||
- **Stdin**: Receives MCP protocol messages
|
||||
- **Stdout**: Sends MCP protocol responses
|
||||
- **Stderr**: Used for logging and diagnostics
|
||||
|
||||
## Error Handling Patterns
|
||||
|
||||
### Tool Error Response
|
||||
|
||||
```typescript
|
||||
try {
|
||||
// Tool implementation
|
||||
return {
|
||||
content: [{
|
||||
type: 'text',
|
||||
text: 'Success result'
|
||||
}]
|
||||
};
|
||||
} catch (error) {
|
||||
const errorMessage = error instanceof Error ? error.message : String(error);
|
||||
|
||||
// Log to stderr for debugging
|
||||
console.error(`[Error] Tool: ${name}, Error: ${errorMessage}`);
|
||||
|
||||
// Return error response with isError flag
|
||||
return {
|
||||
content: [{
|
||||
type: 'text',
|
||||
text: `Error: ${errorMessage}`
|
||||
}],
|
||||
isError: true // Important: Indicates tool failure
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Startup Error Handling
|
||||
|
||||
```typescript
|
||||
main().catch((error) => {
|
||||
console.error('Startup error:', error);
|
||||
process.exit(1); // Exit with error code
|
||||
});
|
||||
```
|
||||
|
||||
## Response Formatting
|
||||
|
||||
### Success Response Structure
|
||||
|
||||
```typescript
|
||||
{
|
||||
content: [
|
||||
{
|
||||
type: 'text',
|
||||
text: 'Response text'
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Error Response Structure
|
||||
|
||||
```typescript
|
||||
{
|
||||
content: [
|
||||
{
|
||||
type: 'text',
|
||||
text: 'Error: Description'
|
||||
}
|
||||
],
|
||||
isError: true
|
||||
}
|
||||
```
|
||||
|
||||
### Resource Link Response
|
||||
|
||||
```typescript
|
||||
{
|
||||
content: [
|
||||
{
|
||||
type: 'resource_link',
|
||||
uri: 'file:///path/to/resource',
|
||||
name: 'Resource Name',
|
||||
mimeType: 'text/plain',
|
||||
description: 'Resource description'
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Lifecycle Management
|
||||
|
||||
### Initialization Pattern
|
||||
|
||||
```typescript
|
||||
async function initializeServer(): Promise<void> {
|
||||
try {
|
||||
// Initialize backend connections
|
||||
await backend.connect();
|
||||
console.error('Backend initialized');
|
||||
} catch (error) {
|
||||
console.error('Initialization failed:', error);
|
||||
throw error; // Prevent server startup
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Shutdown Pattern
|
||||
|
||||
```typescript
|
||||
function setupShutdownHandlers(): void {
|
||||
const handleShutdown = async (signal: string) => {
|
||||
console.error(`Received ${signal}, shutting down...`);
|
||||
|
||||
try {
|
||||
await backend.disconnect();
|
||||
process.exit(0); // Clean exit
|
||||
} catch (error) {
|
||||
console.error('Shutdown error:', error);
|
||||
process.exit(1); // Error exit
|
||||
}
|
||||
};
|
||||
|
||||
process.on('SIGINT', () => handleShutdown('SIGINT'));
|
||||
process.on('SIGTERM', () => handleShutdown('SIGTERM'));
|
||||
|
||||
// Handle unexpected errors
|
||||
process.on('uncaughtException', async (error) => {
|
||||
console.error('Uncaught exception:', error);
|
||||
await backend.disconnect();
|
||||
process.exit(1);
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices Summary
|
||||
|
||||
1. **Server Creation**
|
||||
- Use low-level Server for custom routing
|
||||
- Use McpServer for standard implementations
|
||||
|
||||
2. **Transport Usage**
|
||||
- Initialize backends before connecting transport
|
||||
- Use StdioServerTransport for CLI tools
|
||||
- Log to stderr, not stdout
|
||||
|
||||
3. **Error Handling**
|
||||
- Always validate tool arguments
|
||||
- Include isError flag in error responses
|
||||
- Log errors to stderr with context
|
||||
|
||||
4. **Response Format**
|
||||
- Always return content array
|
||||
- Use consistent type/text structure
|
||||
- Include isError for failures
|
||||
|
||||
5. **Lifecycle**
|
||||
- Clean initialization sequence
|
||||
- Graceful shutdown handlers
|
||||
- Proper exit codes (0 for success, 1 for error)
|
||||
|
||||
## References
|
||||
|
||||
- [MCP TypeScript SDK README](https://github.com/modelcontextprotocol/typescript-sdk)
|
||||
- [Low-Level Server Pattern](https://github.com/modelcontextprotocol/typescript-sdk#low-level-server-implementation)
|
||||
- [Stdio Transport Example](https://github.com/modelcontextprotocol/typescript-sdk#stdio-transport)
|
||||
- [Error Handling Examples](https://github.com/modelcontextprotocol/typescript-sdk#sqlite-explorer)
|
||||
@@ -1,345 +0,0 @@
|
||||
# MCP TypeScript SDK Stdio Transport Guide
|
||||
|
||||
## Documentation Source
|
||||
- **SDK Version**: @modelcontextprotocol/sdk v1.0.0
|
||||
- **Last Verified**: 2025-09-01
|
||||
- **Official Docs**: https://github.com/modelcontextprotocol/typescript-sdk
|
||||
|
||||
## Stdio Transport Overview
|
||||
|
||||
The StdioServerTransport enables MCP servers to communicate via standard input/output streams, making them ideal for CLI tools and direct integrations with Claude Code.
|
||||
|
||||
## Communication Channels
|
||||
|
||||
### Stream Usage
|
||||
- **stdin**: Receives MCP protocol messages (JSON-RPC)
|
||||
- **stdout**: Sends MCP protocol responses (JSON-RPC)
|
||||
- **stderr**: Logging and diagnostic output
|
||||
|
||||
### Important Rules
|
||||
1. **Never write non-protocol data to stdout** - This will break the protocol
|
||||
2. **Always use console.error() for logging** - Goes to stderr
|
||||
3. **Handle binary data carefully** - Protocol is text-based JSON
|
||||
|
||||
## Implementation Patterns
|
||||
|
||||
### Basic Stdio Server Setup
|
||||
|
||||
```typescript
|
||||
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
|
||||
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
|
||||
|
||||
// Create server
|
||||
const server = new Server(
|
||||
{ name: 'my-server', version: '1.0.0' },
|
||||
{ capabilities: { tools: {} } }
|
||||
);
|
||||
|
||||
// Create and connect transport
|
||||
const transport = new StdioServerTransport();
|
||||
await server.connect(transport);
|
||||
|
||||
// Server is now listening on stdin/stdout
|
||||
console.error('Server started'); // Note: console.error for logging
|
||||
```
|
||||
|
||||
### With McpServer (High-Level API)
|
||||
|
||||
```typescript
|
||||
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
||||
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
|
||||
|
||||
const server = new McpServer({
|
||||
name: 'my-server',
|
||||
version: '1.0.0'
|
||||
});
|
||||
|
||||
// Register tools, resources, prompts...
|
||||
server.registerTool(...);
|
||||
|
||||
// Connect to stdio
|
||||
const transport = new StdioServerTransport();
|
||||
await server.connect(transport);
|
||||
```
|
||||
|
||||
## CLI Entry Point Pattern
|
||||
|
||||
### Proper Module Detection (ES Modules)
|
||||
|
||||
```typescript
|
||||
#!/usr/bin/env node
|
||||
|
||||
import { fileURLToPath } from 'url';
|
||||
import { dirname } from 'path';
|
||||
|
||||
const __filename = fileURLToPath(import.meta.url);
|
||||
const __dirname = dirname(__filename);
|
||||
|
||||
// Only run if executed directly
|
||||
if (process.argv[1] === __filename ||
|
||||
process.argv[1].endsWith('server.js')) {
|
||||
main().catch((error) => {
|
||||
console.error('Startup error:', error);
|
||||
process.exit(1);
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
### Main Function Pattern
|
||||
|
||||
```typescript
|
||||
async function main(): Promise<void> {
|
||||
try {
|
||||
// 1. Initialize dependencies
|
||||
await initializeDatabase();
|
||||
|
||||
// 2. Create server
|
||||
const server = createServer();
|
||||
|
||||
// 3. Create transport
|
||||
const transport = new StdioServerTransport();
|
||||
|
||||
// 4. Connect
|
||||
await server.connect(transport);
|
||||
|
||||
// 5. Setup shutdown handlers
|
||||
setupShutdownHandlers();
|
||||
|
||||
// 6. Log readiness to stderr
|
||||
console.error('MCP server ready on stdio');
|
||||
|
||||
} catch (error) {
|
||||
console.error('Failed to start server:', error);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Shutdown Handling
|
||||
|
||||
### Graceful Shutdown Pattern
|
||||
|
||||
```typescript
|
||||
function setupShutdownHandlers(): void {
|
||||
const shutdown = async (signal: string) => {
|
||||
console.error(`\nReceived ${signal}, shutting down...`);
|
||||
|
||||
try {
|
||||
// Clean up resources
|
||||
await cleanupResources();
|
||||
|
||||
// Note: Transport cleanup is handled automatically
|
||||
process.exit(0);
|
||||
} catch (error) {
|
||||
console.error('Shutdown error:', error);
|
||||
process.exit(1);
|
||||
}
|
||||
};
|
||||
|
||||
// Handle termination signals
|
||||
process.on('SIGINT', () => shutdown('SIGINT')); // Ctrl+C
|
||||
process.on('SIGTERM', () => shutdown('SIGTERM')); // Kill
|
||||
process.on('SIGHUP', () => shutdown('SIGHUP')); // Terminal closed
|
||||
|
||||
// Handle errors
|
||||
process.on('uncaughtException', (error) => {
|
||||
console.error('Uncaught exception:', error);
|
||||
process.exit(1);
|
||||
});
|
||||
|
||||
process.on('unhandledRejection', (reason) => {
|
||||
console.error('Unhandled rejection:', reason);
|
||||
process.exit(1);
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## Logging Best Practices
|
||||
|
||||
### Do's and Don'ts
|
||||
|
||||
```typescript
|
||||
// ✅ DO: Log to stderr
|
||||
console.error('Server initialized');
|
||||
console.error('Processing request:', requestId);
|
||||
console.error('Debug info:', { data });
|
||||
|
||||
// ❌ DON'T: Log to stdout
|
||||
console.log('This breaks the protocol!'); // NEVER DO THIS
|
||||
|
||||
// ✅ DO: Use structured logging to stderr
|
||||
const log = (level: string, message: string, data?: any) => {
|
||||
console.error(JSON.stringify({
|
||||
timestamp: new Date().toISOString(),
|
||||
level,
|
||||
message,
|
||||
...data
|
||||
}));
|
||||
};
|
||||
|
||||
log('info', 'Server started', { port: 'stdio' });
|
||||
```
|
||||
|
||||
### Debug Mode Pattern
|
||||
|
||||
```typescript
|
||||
const DEBUG = process.env.DEBUG === 'true';
|
||||
|
||||
const debug = (message: string, ...args: any[]) => {
|
||||
if (DEBUG) {
|
||||
console.error(`[DEBUG] ${message}`, ...args);
|
||||
}
|
||||
};
|
||||
|
||||
// Usage
|
||||
debug('Request received:', request);
|
||||
```
|
||||
|
||||
## Testing Stdio Servers
|
||||
|
||||
### Manual Testing
|
||||
|
||||
```bash
|
||||
# Start server and interact manually
|
||||
node dist/server.js
|
||||
|
||||
# With debug logging
|
||||
DEBUG=true node dist/server.js
|
||||
|
||||
# Pipe test input
|
||||
echo '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}' | node dist/server.js
|
||||
```
|
||||
|
||||
### Automated Testing Pattern
|
||||
|
||||
```typescript
|
||||
import { spawn } from 'child_process';
|
||||
|
||||
function testServer() {
|
||||
const server = spawn('node', ['dist/server.js']);
|
||||
|
||||
// Capture stderr for logs
|
||||
server.stderr.on('data', (data) => {
|
||||
console.log('Server log:', data.toString());
|
||||
});
|
||||
|
||||
// Capture stdout for protocol
|
||||
let response = '';
|
||||
server.stdout.on('data', (data) => {
|
||||
response += data.toString();
|
||||
// Parse and validate response
|
||||
});
|
||||
|
||||
// Send test request
|
||||
server.stdin.write(JSON.stringify({
|
||||
jsonrpc: '2.0',
|
||||
method: 'initialize',
|
||||
params: {},
|
||||
id: 1
|
||||
}));
|
||||
server.stdin.end();
|
||||
}
|
||||
```
|
||||
|
||||
## Common Issues and Solutions
|
||||
|
||||
### Issue 1: Protocol Corruption
|
||||
|
||||
**Problem**: Random text in stdout breaks communication
|
||||
**Solution**: Always use console.error() for logging
|
||||
|
||||
```typescript
|
||||
// Wrong
|
||||
console.log('Debug:', data); // Breaks protocol
|
||||
|
||||
// Right
|
||||
console.error('Debug:', data); // Safe for debugging
|
||||
```
|
||||
|
||||
### Issue 2: Server Not Responding
|
||||
|
||||
**Problem**: Server starts but doesn't respond to requests
|
||||
**Solution**: Ensure transport is connected
|
||||
|
||||
```typescript
|
||||
// Check connection is awaited
|
||||
await server.connect(transport); // Must await!
|
||||
console.error('Transport connected');
|
||||
```
|
||||
|
||||
### Issue 3: Premature Exit
|
||||
|
||||
**Problem**: Server exits immediately
|
||||
**Solution**: Don't close stdin/stdout
|
||||
|
||||
```typescript
|
||||
// Wrong
|
||||
process.stdin.end(); // Don't do this
|
||||
|
||||
// Right
|
||||
// Let the transport manage streams
|
||||
```
|
||||
|
||||
## Integration with Claude Code
|
||||
|
||||
### Configuration in .claude.json
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-server": {
|
||||
"command": "node",
|
||||
"args": ["/path/to/dist/server.js"],
|
||||
"env": {
|
||||
"DEBUG": "false"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Best Practices for Claude Code Integration
|
||||
|
||||
1. **Startup Messages**: Log clear startup messages to stderr
|
||||
2. **Error Messages**: Provide actionable error messages
|
||||
3. **Ready Signal**: Log when server is ready to accept requests
|
||||
4. **Version Info**: Include version in startup logs
|
||||
|
||||
```typescript
|
||||
console.error(`Starting ${serverName} v${version}`);
|
||||
console.error('Initializing...');
|
||||
// ... initialization ...
|
||||
console.error(`${serverName} ready on stdio`);
|
||||
```
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Buffering and Streaming
|
||||
|
||||
```typescript
|
||||
// For large responses, consider streaming
|
||||
import { Transform } from 'stream';
|
||||
|
||||
class ResponseStream extends Transform {
|
||||
_transform(chunk: any, encoding: string, callback: Function) {
|
||||
// Process chunk
|
||||
this.push(JSON.stringify(chunk));
|
||||
callback();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Memory Management
|
||||
|
||||
```typescript
|
||||
// Clear large objects after use
|
||||
let largeData = await processData();
|
||||
// Use data...
|
||||
largeData = null; // Allow GC
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- [StdioServerTransport Docs](https://github.com/modelcontextprotocol/typescript-sdk#stdio-transport)
|
||||
- [Server Examples](https://github.com/modelcontextprotocol/typescript-sdk/tree/main/src/examples/server)
|
||||
- [MCP Protocol Specification](https://modelcontextprotocol.io/docs)
|
||||
+20
-12
@@ -9,6 +9,7 @@
|
||||
*/
|
||||
|
||||
import { loadCliCommand } from './shared/config-loader.js';
|
||||
import { getLogsDir } from './shared/path-resolver.js';
|
||||
import {
|
||||
createHookResponse,
|
||||
executeCliCommand,
|
||||
@@ -16,7 +17,11 @@ import {
|
||||
debugLog
|
||||
} from './shared/hook-helpers.js';
|
||||
|
||||
const cliCommand = loadCliCommand();
|
||||
|
||||
// Set up stdin immediately
|
||||
process.stdin.setEncoding('utf8');
|
||||
process.stdin.resume(); // Explicitly enter flowing mode to prevent data loss
|
||||
|
||||
|
||||
// Read input from stdin
|
||||
let input = '';
|
||||
@@ -25,7 +30,11 @@ process.stdin.on('data', chunk => {
|
||||
});
|
||||
|
||||
process.stdin.on('end', async () => {
|
||||
|
||||
try {
|
||||
// Load CLI command inside try-catch to handle config errors properly
|
||||
const cliCommand = loadCliCommand();
|
||||
|
||||
const payload = JSON.parse(input);
|
||||
debugLog('Pre-compact hook started', { payload });
|
||||
|
||||
@@ -33,17 +42,18 @@ process.stdin.on('end', async () => {
|
||||
const validation = validateHookPayload(payload, 'PreCompact');
|
||||
if (!validation.valid) {
|
||||
const response = createHookResponse('PreCompact', false, { reason: validation.error });
|
||||
console.log(JSON.stringify(response));
|
||||
debugLog('Validation failed', { response });
|
||||
// Exit silently - validation failure is expected flow control
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
// Check for environment-based blocking conditions
|
||||
if (payload.trigger === 'auto' && process.env.DISABLE_AUTO_COMPRESSION === 'true') {
|
||||
debugLog('Auto-compression disabled by configuration');
|
||||
const response = createHookResponse('PreCompact', false, {
|
||||
reason: 'Auto-compression disabled by configuration'
|
||||
});
|
||||
console.log(JSON.stringify(response));
|
||||
debugLog('Auto-compression disabled', { response });
|
||||
// Exit silently - disabled compression is expected flow control
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
@@ -56,26 +66,24 @@ process.stdin.on('end', async () => {
|
||||
const result = await executeCliCommand(cliCommand, ['compress', payload.transcript_path]);
|
||||
|
||||
if (!result.success) {
|
||||
debugLog('Compression command failed', { stderr: result.stderr });
|
||||
const response = createHookResponse('PreCompact', false, {
|
||||
reason: `Compression failed: ${result.stderr || 'Unknown error'}`
|
||||
});
|
||||
console.log(JSON.stringify(response));
|
||||
process.exit(0);
|
||||
debugLog('Compression command failed', { stderr: result.stderr, response });
|
||||
console.log(`claude-mem error: compression failed, see logs at ${getLogsDir()}`);
|
||||
process.exit(1); // Exit with error code for actual compression failure
|
||||
}
|
||||
|
||||
// Success - create standardized approval response using HookTemplates
|
||||
// Success - exit silently (suppressOutput is true)
|
||||
debugLog('Compression completed successfully');
|
||||
const response = createHookResponse('PreCompact', true);
|
||||
console.log(JSON.stringify(response));
|
||||
process.exit(0);
|
||||
|
||||
} catch (error) {
|
||||
debugLog('Pre-compact hook error', { error: error.message });
|
||||
const response = createHookResponse('PreCompact', false, {
|
||||
reason: `Hook execution error: ${error.message}`
|
||||
});
|
||||
console.log(JSON.stringify(response));
|
||||
debugLog('Pre-compact hook error', { error: error.message, response });
|
||||
console.log(`claude-mem error: hook failed, see logs at ${getLogsDir()}`);
|
||||
process.exit(1);
|
||||
}
|
||||
});
|
||||
@@ -5,16 +5,15 @@
|
||||
*/
|
||||
|
||||
import { loadCliCommand } from './shared/config-loader.js';
|
||||
import { getSettingsPath, getArchivesDir } from './shared/path-resolver.js';
|
||||
import { execSync } from 'child_process';
|
||||
import { join } from 'path';
|
||||
import { homedir } from 'os';
|
||||
import { existsSync, readFileSync } from 'fs';
|
||||
|
||||
const cliCommand = loadCliCommand();
|
||||
|
||||
// Check if save-on-clear is enabled
|
||||
function isSaveOnClearEnabled() {
|
||||
const settingsPath = join(homedir(), '.claude-mem', 'settings.json');
|
||||
const settingsPath = getSettingsPath();
|
||||
if (existsSync(settingsPath)) {
|
||||
try {
|
||||
const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
|
||||
@@ -26,6 +25,10 @@ function isSaveOnClearEnabled() {
|
||||
return false;
|
||||
}
|
||||
|
||||
// Set up stdin immediately before any async operations
|
||||
process.stdin.setEncoding('utf8');
|
||||
process.stdin.resume(); // Explicitly enter flowing mode to prevent data loss
|
||||
|
||||
// Read input
|
||||
let input = '';
|
||||
process.stdin.on('data', chunk => {
|
||||
@@ -41,7 +44,7 @@ process.stdin.on('end', async () => {
|
||||
|
||||
try {
|
||||
// Use the CLI to compress current transcript
|
||||
execSync(`${cliCommand} compress --output ${homedir()}/.claude-mem/archives`, {
|
||||
execSync(`${cliCommand} compress --output ${getArchivesDir()}`, {
|
||||
stdio: 'inherit',
|
||||
env: { ...process.env, CLAUDE_MEM_SILENT: 'true' }
|
||||
});
|
||||
|
||||
+10
-6
@@ -21,6 +21,10 @@ import {
|
||||
|
||||
const cliCommand = loadCliCommand();
|
||||
|
||||
// Set up stdin immediately before any async operations
|
||||
process.stdin.setEncoding('utf8');
|
||||
process.stdin.resume(); // Explicitly enter flowing mode to prevent data loss
|
||||
|
||||
// Read input from stdin
|
||||
let input = '';
|
||||
process.stdin.on('data', chunk => {
|
||||
@@ -47,14 +51,14 @@ process.stdin.on('end', async () => {
|
||||
// Skip load-context when source is "resume" to avoid duplicate context
|
||||
if (payload.source === 'resume') {
|
||||
debugLog('Skipping load-context for resume source');
|
||||
// Output nothing at all for resume - no message, no context
|
||||
// Output valid JSON response with suppressOutput for resume
|
||||
const response = createHookResponse('SessionStart', true);
|
||||
console.log(JSON.stringify(response));
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
// Extract project name from current working directory and sanitize
|
||||
const rawProjectName = path.basename(process.cwd());
|
||||
const projectName = rawProjectName.replace(/-/g, '_');
|
||||
debugLog('Extracted project name', { rawProjectName, projectName });
|
||||
// Extract project name from current working directory
|
||||
const projectName = path.basename(process.cwd());
|
||||
|
||||
// Load context using standardized CLI execution helper
|
||||
const contextResult = await executeCliCommand(cliCommand, [
|
||||
@@ -152,7 +156,7 @@ function extractProjectName(transcriptPath) {
|
||||
|
||||
// Look for project pattern: /path/to/PROJECT_NAME/.claude/
|
||||
// Need to get PROJECT_NAME, not the parent directory
|
||||
const parts = transcriptPath.split('/');
|
||||
const parts = transcriptPath.split(path.sep);
|
||||
const claudeIndex = parts.indexOf('.claude');
|
||||
|
||||
if (claudeIndex > 0) {
|
||||
|
||||
@@ -47,13 +47,10 @@ export function createHookResponse(hookType, success, options = {}) {
|
||||
}
|
||||
};
|
||||
} else if (success) {
|
||||
// No context - just suppress output without any message
|
||||
return {
|
||||
continue: true,
|
||||
suppressOutput: true,
|
||||
hookSpecificOutput: {
|
||||
hookEventName: 'SessionStart',
|
||||
additionalContext: 'Starting fresh session - no previous context available'
|
||||
}
|
||||
suppressOutput: true
|
||||
};
|
||||
} else {
|
||||
return {
|
||||
|
||||
@@ -0,0 +1,63 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
/**
|
||||
* Path resolver utility for Claude Memory hooks
|
||||
* Provides proper path handling using environment variables
|
||||
*/
|
||||
|
||||
import { join } from 'path';
|
||||
import { homedir } from 'os';
|
||||
|
||||
/**
|
||||
* Gets the base data directory for claude-mem
|
||||
* @returns {string} Data directory path
|
||||
*/
|
||||
export function getDataDir() {
|
||||
return process.env.CLAUDE_MEM_DATA_DIR || join(homedir(), '.claude-mem');
|
||||
}
|
||||
|
||||
/**
|
||||
* Gets the settings file path
|
||||
* @returns {string} Settings file path
|
||||
*/
|
||||
export function getSettingsPath() {
|
||||
return join(getDataDir(), 'settings.json');
|
||||
}
|
||||
|
||||
/**
|
||||
* Gets the archives directory path
|
||||
* @returns {string} Archives directory path
|
||||
*/
|
||||
export function getArchivesDir() {
|
||||
return process.env.CLAUDE_MEM_ARCHIVES_DIR || join(getDataDir(), 'archives');
|
||||
}
|
||||
|
||||
/**
|
||||
* Gets the logs directory path
|
||||
* @returns {string} Logs directory path
|
||||
*/
|
||||
export function getLogsDir() {
|
||||
return process.env.CLAUDE_MEM_LOGS_DIR || join(getDataDir(), 'logs');
|
||||
}
|
||||
|
||||
/**
|
||||
* Gets the compact flag file path
|
||||
* @returns {string} Compact flag file path
|
||||
*/
|
||||
export function getCompactFlagPath() {
|
||||
return join(getDataDir(), '.compact-running');
|
||||
}
|
||||
|
||||
/**
|
||||
* Gets all common paths used by hooks
|
||||
* @returns {Object} Object containing all common paths
|
||||
*/
|
||||
export function getPaths() {
|
||||
return {
|
||||
dataDir: getDataDir(),
|
||||
settingsPath: getSettingsPath(),
|
||||
archivesDir: getArchivesDir(),
|
||||
logsDir: getLogsDir(),
|
||||
compactFlagPath: getCompactFlagPath()
|
||||
};
|
||||
}
|
||||
-58
@@ -1,58 +0,0 @@
|
||||
#!/bin/bash
|
||||
# Claude Mem Installation Script
|
||||
|
||||
set -e
|
||||
|
||||
VERSION="${1:-latest}"
|
||||
PLATFORM=""
|
||||
ARCH=$(uname -m)
|
||||
OS=$(uname -s)
|
||||
|
||||
# Detect platform
|
||||
case "$OS" in
|
||||
Darwin)
|
||||
if [ "$ARCH" = "arm64" ]; then
|
||||
PLATFORM="macos-arm64"
|
||||
BINARY="claude-mem-macos-arm64"
|
||||
else
|
||||
PLATFORM="macos-x64"
|
||||
BINARY="claude-mem-macos-x64"
|
||||
fi
|
||||
;;
|
||||
Linux)
|
||||
if [ "$ARCH" = "aarch64" ]; then
|
||||
PLATFORM="linux-arm64"
|
||||
BINARY="claude-mem-linux-arm64"
|
||||
else
|
||||
PLATFORM="linux-x64"
|
||||
BINARY="claude-mem-linux"
|
||||
fi
|
||||
;;
|
||||
MINGW*|MSYS*|CYGWIN*)
|
||||
PLATFORM="windows-x64"
|
||||
BINARY="claude-mem.exe"
|
||||
;;
|
||||
*)
|
||||
echo "Unsupported platform: $OS $ARCH"
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
|
||||
echo "📥 Downloading Claude Mem for $PLATFORM..."
|
||||
|
||||
# Download binary from GitHub releases
|
||||
if [ "$VERSION" = "latest" ]; then
|
||||
DOWNLOAD_URL="https://github.com/thedotmack/claude-mem/releases/latest/download/${BINARY}"
|
||||
else
|
||||
DOWNLOAD_URL="https://github.com/thedotmack/claude-mem/releases/download/${VERSION}/${BINARY}"
|
||||
fi
|
||||
|
||||
curl -L -o claude-mem "$DOWNLOAD_URL"
|
||||
|
||||
# Make executable (non-Windows)
|
||||
if [ "$OS" != "MINGW" ] && [ "$OS" != "MSYS" ] && [ "$OS" != "CYGWIN" ]; then
|
||||
chmod +x claude-mem
|
||||
fi
|
||||
|
||||
echo "✅ Claude Mem installed successfully!"
|
||||
echo "Run ./claude-mem --help to get started"
|
||||
@@ -0,0 +1,59 @@
|
||||
{
|
||||
"name": "claude-mem",
|
||||
"version": "3.6.10",
|
||||
"description": "Memory compression system for Claude Code - persist context across sessions",
|
||||
"keywords": [
|
||||
"claude",
|
||||
"claude-code",
|
||||
"mcp",
|
||||
"memory",
|
||||
"compression",
|
||||
"knowledge-graph",
|
||||
"transcript",
|
||||
"cli",
|
||||
"typescript",
|
||||
"bun"
|
||||
],
|
||||
"author": "Alex Newman",
|
||||
"license": "SEE LICENSE IN LICENSE",
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://github.com/thedotmack/claude-mem.git"
|
||||
},
|
||||
"homepage": "https://github.com/thedotmack/claude-mem#readme",
|
||||
"bugs": {
|
||||
"url": "https://github.com/thedotmack/claude-mem/issues"
|
||||
},
|
||||
"publishConfig": {
|
||||
"access": "public",
|
||||
"registry": "https://registry.npmjs.org/"
|
||||
},
|
||||
"type": "module",
|
||||
"engines": {
|
||||
"node": ">=18.0.0"
|
||||
},
|
||||
"bin": {
|
||||
"claude-mem": "./dist/claude-mem.min.js"
|
||||
},
|
||||
"dependencies": {
|
||||
"@anthropic-ai/claude-code": "^1.0.88",
|
||||
"@clack/prompts": "^0.11.0",
|
||||
"@modelcontextprotocol/sdk": "^0.5.0",
|
||||
"boxen": "^8.0.1",
|
||||
"chalk": "^5.6.0",
|
||||
"chromadb": "^3.0.14",
|
||||
"commander": "^14.0.0",
|
||||
"glob": "^11.0.3",
|
||||
"gradient-string": "^3.0.0",
|
||||
"handlebars": "^4.7.8",
|
||||
"oh-my-logo": "^0.3.2"
|
||||
},
|
||||
"files": [
|
||||
"dist",
|
||||
"hooks",
|
||||
"commands",
|
||||
"src",
|
||||
".mcp.json",
|
||||
"CHANGELOG.md"
|
||||
]
|
||||
}
|
||||
+248
@@ -0,0 +1,248 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
// <Block> 1.1 ====================================
|
||||
// CLI Dependencies and Imports Setup
|
||||
// Natural pattern: Import what you need before using it
|
||||
import { Command } from 'commander';
|
||||
import { PACKAGE_NAME, PACKAGE_VERSION, PACKAGE_DESCRIPTION } from '../shared/config.js';
|
||||
|
||||
// Import command handlers
|
||||
import { compress } from '../commands/compress.js';
|
||||
import { install } from '../commands/install.js';
|
||||
import { uninstall } from '../commands/uninstall.js';
|
||||
import { status } from '../commands/status.js';
|
||||
import { logs } from '../commands/logs.js';
|
||||
import { loadContext } from '../commands/load-context.js';
|
||||
import { trash } from '../commands/trash.js';
|
||||
import { restore } from '../commands/restore.js';
|
||||
import { save } from '../commands/save.js';
|
||||
import { changelog } from '../commands/changelog.js';
|
||||
// Cloud functionality disabled - incomplete setup
|
||||
// import { cloudCommand } from '../commands/cloud.js';
|
||||
import { importHistory } from '../commands/import-history.js';
|
||||
import { TranscriptCompressor } from '../core/compression/TranscriptCompressor.js';
|
||||
|
||||
const program = new Command();
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 1.2 ====================================
|
||||
// Program Configuration
|
||||
// Natural pattern: Configure program metadata first
|
||||
program
|
||||
.name(PACKAGE_NAME)
|
||||
.description(PACKAGE_DESCRIPTION)
|
||||
.version(PACKAGE_VERSION);
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 1.3 ====================================
|
||||
// Compress Command Definition
|
||||
// Natural pattern: Define command with its options and handler
|
||||
// Compress command
|
||||
program
|
||||
.command('compress [transcript]')
|
||||
.description('Compress a Claude Code transcript into memory')
|
||||
.option('--output <path>', 'Output directory for compressed files')
|
||||
.option('--dry-run', 'Show what would be compressed without doing it')
|
||||
.option('-v, --verbose', 'Show detailed output')
|
||||
.action(compress);
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 1.4 ====================================
|
||||
// Install Command Definition
|
||||
// Natural pattern: Define command with its options and handler
|
||||
// Install command
|
||||
program
|
||||
.command('install')
|
||||
.description('Install Claude Code hooks for automatic compression')
|
||||
.option('--user', 'Install for current user (default)')
|
||||
.option('--project', 'Install for current project only')
|
||||
.option('--local', 'Install to custom local directory')
|
||||
.option('--path <path>', 'Custom installation path (with --local)')
|
||||
.option('--timeout <ms>', 'Hook execution timeout in milliseconds', '180000')
|
||||
.option('--skip-mcp', 'Skip Chroma MCP server installation')
|
||||
.option('--force', 'Force installation even if already installed')
|
||||
.action(install);
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 1.5 ====================================
|
||||
// Uninstall Command Definition
|
||||
// Natural pattern: Define command with its options and handler
|
||||
// Uninstall command
|
||||
program
|
||||
.command('uninstall')
|
||||
.description('Remove Claude Code hooks')
|
||||
.option('--user', 'Remove from user settings (default)')
|
||||
.option('--project', 'Remove from project settings')
|
||||
.option('--all', 'Remove from both user and project settings')
|
||||
.action(uninstall);
|
||||
// </Block> =======================================
|
||||
|
||||
|
||||
// <Block> 1.6 ====================================
|
||||
// Status Command Definition
|
||||
// Natural pattern: Define command with its handler
|
||||
// Status command
|
||||
program
|
||||
.command('status')
|
||||
.description('Check installation status of Claude Memory System')
|
||||
.action(status);
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 1.7 ====================================
|
||||
// Logs Command Definition
|
||||
// Natural pattern: Define command with its options and handler
|
||||
// Logs command
|
||||
program
|
||||
.command('logs')
|
||||
.description('View claude-mem operation logs')
|
||||
.option('--debug', 'Show debug logs only')
|
||||
.option('--error', 'Show error logs only')
|
||||
.option('--tail [n]', 'Show last n lines', '50')
|
||||
.option('--follow', 'Follow log output')
|
||||
.action(logs);
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 1.8 ====================================
|
||||
// Load-Context Command Definition
|
||||
// Natural pattern: Define command with its options and handler
|
||||
// Load-context command
|
||||
program
|
||||
.command('load-context')
|
||||
.description('Load compressed memories for current session')
|
||||
.option('--project <name>', 'Filter by project name')
|
||||
.option('--count <n>', 'Number of memories to load', '10')
|
||||
.option('--raw', 'Output raw JSON instead of formatted text')
|
||||
.option('--format <type>', 'Output format: json, session-start, or default')
|
||||
.action(loadContext);
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 1.9 ====================================
|
||||
// Trash and Restore Commands Definition
|
||||
// Natural pattern: Define commands for safe file operations
|
||||
|
||||
// Trash command with subcommands
|
||||
const trashCmd = program
|
||||
.command('trash')
|
||||
.description('Manage trash bin for safe file deletion')
|
||||
.argument('[files...]', 'Files to move to trash')
|
||||
.option('-r, --recursive', 'Remove directories recursively')
|
||||
.option('-R', 'Remove directories recursively (same as -r)')
|
||||
.option('-f, --force', 'Suppress errors for nonexistent files')
|
||||
.action(async (files: string[] | undefined, options: any) => {
|
||||
// If no files provided, show help
|
||||
if (!files || files.length === 0) {
|
||||
trashCmd.outputHelp();
|
||||
return;
|
||||
}
|
||||
|
||||
// Map -R to recursive
|
||||
if (options.R) options.recursive = true;
|
||||
|
||||
await trash(files, {
|
||||
force: options.force,
|
||||
recursive: options.recursive
|
||||
});
|
||||
});
|
||||
|
||||
// Trash view subcommand
|
||||
trashCmd
|
||||
.command('view')
|
||||
.description('View contents of trash bin')
|
||||
.action(async () => {
|
||||
const { viewTrash } = await import('../commands/trash-view.js');
|
||||
await viewTrash();
|
||||
});
|
||||
|
||||
// Trash empty subcommand
|
||||
trashCmd
|
||||
.command('empty')
|
||||
.description('Permanently delete all files in trash')
|
||||
.option('-f, --force', 'Skip confirmation prompt')
|
||||
.action(async (options: any) => {
|
||||
const { emptyTrash } = await import('../commands/trash-empty.js');
|
||||
await emptyTrash(options);
|
||||
});
|
||||
|
||||
// Restore command
|
||||
program
|
||||
.command('restore')
|
||||
.description('Restore files from trash interactively')
|
||||
.action(restore);
|
||||
// </Block> =======================================
|
||||
|
||||
// Cloud command
|
||||
// Cloud functionality disabled - incomplete setup
|
||||
// program.addCommand(cloudCommand);
|
||||
|
||||
// Save command
|
||||
program
|
||||
.command('save <message>')
|
||||
.description('Save a message to the memory system')
|
||||
.action(save);
|
||||
|
||||
// Changelog command
|
||||
program
|
||||
.command('changelog')
|
||||
.description('Generate CHANGELOG.md from claude-mem memories')
|
||||
.option('--historical <n>', 'Number of versions to search (default: current version only)')
|
||||
.option('--generate <version>', 'Generate changelog for a specific version')
|
||||
.option('--start <time>', 'Start time for memory search (ISO format)')
|
||||
.option('--end <time>', 'End time for memory search (ISO format)')
|
||||
.option('--update', 'Update CHANGELOG.md from JSONL entries')
|
||||
.option('--preview', 'Preview the generated changelog')
|
||||
.option('-v, --verbose', 'Show detailed output')
|
||||
.action(changelog);
|
||||
|
||||
// Import History command
|
||||
program
|
||||
.command('import-history')
|
||||
.description('Import historical Claude Code conversations into memory')
|
||||
.option('-v, --verbose', 'Show detailed output')
|
||||
.option('-m, --multi', 'Enable multi-select mode (default is single-select)')
|
||||
.action(importHistory);
|
||||
|
||||
// <Block> 1.11 ===================================
|
||||
// Hook Commands
|
||||
// Internal commands called by hook scripts
|
||||
program
|
||||
.command('hook:pre-compact', { hidden: true })
|
||||
.description('Internal pre-compact hook handler')
|
||||
.action(async () => {
|
||||
const { preCompactHook } = await import('../commands/hooks.js');
|
||||
await preCompactHook();
|
||||
});
|
||||
|
||||
program
|
||||
.command('hook:session-start', { hidden: true })
|
||||
.description('Internal session-start hook handler')
|
||||
.action(async () => {
|
||||
const { sessionStartHook } = await import('../commands/hooks.js');
|
||||
await sessionStartHook();
|
||||
});
|
||||
|
||||
program
|
||||
.command('hook:session-end', { hidden: true })
|
||||
.description('Internal session-end hook handler')
|
||||
.action(async () => {
|
||||
const { sessionEndHook } = await import('../commands/hooks.js');
|
||||
await sessionEndHook();
|
||||
});
|
||||
|
||||
// </Block> =======================================
|
||||
|
||||
// Debug command to show filtered output
|
||||
program
|
||||
.command('debug-filter')
|
||||
.description('Show filtered transcript output (first 5 messages)')
|
||||
.argument('<transcript-path>', 'Path to transcript file')
|
||||
.action((transcriptPath) => {
|
||||
const compressor = new TranscriptCompressor();
|
||||
compressor.showFilteredOutput(transcriptPath);
|
||||
});
|
||||
|
||||
// <Block> 1.11 ===================================
|
||||
// CLI Execution
|
||||
// Natural pattern: After defining all commands, parse and execute
|
||||
// Parse arguments and execute
|
||||
program.parse();
|
||||
// </Block> =======================================
|
||||
@@ -0,0 +1,744 @@
|
||||
import { OptionValues } from 'commander';
|
||||
import { query } from '@anthropic-ai/claude-code';
|
||||
import fs from 'fs';
|
||||
import path from 'path';
|
||||
import { getClaudePath } from '../shared/settings.js';
|
||||
import { execSync } from 'child_process';
|
||||
|
||||
interface ChangelogEntry {
|
||||
version: string;
|
||||
date: string;
|
||||
type: 'Added' | 'Changed' | 'Fixed' | 'Removed' | 'Deprecated' | 'Security';
|
||||
description: string;
|
||||
timestamp: string;
|
||||
generatedAt?: string; // When this changelog entry was created
|
||||
}
|
||||
|
||||
interface MemorySearchResult {
|
||||
version: string;
|
||||
text: string;
|
||||
metadata: any;
|
||||
}
|
||||
|
||||
export async function changelog(options: OptionValues): Promise<void> {
|
||||
try {
|
||||
// Handle --update flag to regenerate CHANGELOG.md from JSONL
|
||||
if (options.update) {
|
||||
await updateChangelogFromJsonl(options);
|
||||
return;
|
||||
}
|
||||
|
||||
// Get current version and project name from package.json
|
||||
const packageJsonPath = path.join(process.cwd(), 'package.json');
|
||||
let currentVersion = 'unknown';
|
||||
let projectName = 'unknown';
|
||||
if (fs.existsSync(packageJsonPath)) {
|
||||
try {
|
||||
const packageData = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
|
||||
currentVersion = packageData.version || 'unknown';
|
||||
projectName = packageData.name || path.basename(process.cwd());
|
||||
} catch (e) {
|
||||
projectName = path.basename(process.cwd());
|
||||
}
|
||||
}
|
||||
|
||||
// Calculate versions to search for based on flags
|
||||
const versionsToSearch: string[] = [];
|
||||
let historicalCount = options.historical || 1; // Default to current version only
|
||||
|
||||
// Handle --generate flag for specific version
|
||||
if (options.generate) {
|
||||
versionsToSearch.push(options.generate);
|
||||
historicalCount = 1; // Single version mode
|
||||
console.log(`🎯 Generating changelog for specific version: ${options.generate}`);
|
||||
} else if (currentVersion !== 'unknown') {
|
||||
// Normal mode: use current version or historical versions
|
||||
const parts = currentVersion.split('.');
|
||||
if (parts.length === 3) {
|
||||
let major = parseInt(parts[0]);
|
||||
let minor = parseInt(parts[1]);
|
||||
let patch = parseInt(parts[2]);
|
||||
|
||||
for (let i = 0; i < historicalCount; i++) {
|
||||
versionsToSearch.push(`${major}.${minor}.${patch}`);
|
||||
|
||||
// Decrement version
|
||||
if (patch === 0) {
|
||||
if (minor === 0) {
|
||||
// Can't go lower than x.0.0
|
||||
break;
|
||||
}
|
||||
minor--;
|
||||
patch = 9;
|
||||
} else {
|
||||
patch--;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (versionsToSearch.length === 0) {
|
||||
console.log('⚠️ Could not determine versions to search. Please check package.json');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
// Check if current version already has a changelog entry
|
||||
const projectChangelogDir = path.join(
|
||||
process.env.HOME || process.env.USERPROFILE || '',
|
||||
'.claude-mem',
|
||||
'projects'
|
||||
);
|
||||
const changelogJsonlPath = path.join(projectChangelogDir, `${projectName}-changelog.jsonl`);
|
||||
|
||||
let hasCurrentVersion = false;
|
||||
|
||||
if (fs.existsSync(changelogJsonlPath)) {
|
||||
const existingLines = fs.readFileSync(changelogJsonlPath, 'utf-8').split('\n').filter(l => l.trim());
|
||||
|
||||
for (const line of existingLines) {
|
||||
try {
|
||||
const entry = JSON.parse(line);
|
||||
if (entry.version === currentVersion) {
|
||||
hasCurrentVersion = true;
|
||||
}
|
||||
} catch (e) {
|
||||
// Skip invalid lines
|
||||
}
|
||||
}
|
||||
|
||||
if (!options.historical && !options.generate && historicalCount === 1) {
|
||||
if (hasCurrentVersion) {
|
||||
console.log(`❌ Version ${currentVersion} already has changelog entries.`);
|
||||
console.log('\n📝 Workflow:');
|
||||
console.log(' 1. Make your code updates');
|
||||
console.log(' 2. Build and test: bun run build');
|
||||
console.log(' 3. Bump version: npm version patch');
|
||||
console.log(' 4. Generate changelog: claude-mem changelog');
|
||||
console.log(' 5. Commit and push\n');
|
||||
console.log(`💡 Or use --historical 1 to regenerate this version's changelog`);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Get npm publish times for all versions we need
|
||||
let versionTimeRanges: Array<{version: string, startTime: string, endTime: string}> = [];
|
||||
|
||||
// Check if custom time range is provided
|
||||
if (options.start && options.end) {
|
||||
// Use custom time range for the specified version
|
||||
const version = options.generate || currentVersion;
|
||||
versionTimeRanges.push({
|
||||
version,
|
||||
startTime: options.start,
|
||||
endTime: options.end
|
||||
});
|
||||
|
||||
console.log(`📅 Using custom time range for ${version}:`);
|
||||
console.log(` Start: ${new Date(options.start).toLocaleString()}`);
|
||||
console.log(` End: ${new Date(options.end).toLocaleString()}`);
|
||||
} else {
|
||||
try {
|
||||
const npmTimeData = execSync(`npm view ${projectName} time --json`, {
|
||||
encoding: 'utf-8',
|
||||
timeout: 5000
|
||||
});
|
||||
const publishTimes = JSON.parse(npmTimeData);
|
||||
|
||||
// For historical mode, we need one extra previous version to get proper time ranges
|
||||
// E.g., for 3 versions, we need 4 timestamps to create 3 ranges
|
||||
let extraPrevVersion = '';
|
||||
if (historicalCount > 1) {
|
||||
// Get the version before our oldest version in the search list
|
||||
const oldestVersion = versionsToSearch[versionsToSearch.length - 1];
|
||||
const parts = oldestVersion.split('.');
|
||||
const major = parseInt(parts[0]);
|
||||
const minor = parseInt(parts[1]);
|
||||
const patch = parseInt(parts[2]);
|
||||
|
||||
if (patch > 0) {
|
||||
extraPrevVersion = `${major}.${minor}.${patch - 1}`;
|
||||
} else if (minor > 0) {
|
||||
// Look for highest patch of previous minor
|
||||
const prevMinorPrefix = `${major}.${minor - 1}.`;
|
||||
const prevMinorVersions = Object.keys(publishTimes)
|
||||
.filter(v => v.startsWith(prevMinorPrefix))
|
||||
.sort((a, b) => {
|
||||
const aPatch = parseInt(a.split('.')[2] || '0');
|
||||
const bPatch = parseInt(b.split('.')[2] || '0');
|
||||
return bPatch - aPatch;
|
||||
});
|
||||
if (prevMinorVersions.length > 0) {
|
||||
extraPrevVersion = prevMinorVersions[0];
|
||||
}
|
||||
} else if (major > 0) {
|
||||
// Look for highest version of previous major
|
||||
const prevMajorPrefix = `${major - 1}.`;
|
||||
const prevMajorVersions = Object.keys(publishTimes)
|
||||
.filter(v => v.startsWith(prevMajorPrefix))
|
||||
.sort((a, b) => {
|
||||
const [, aMinor, aPatch] = a.split('.').map(Number);
|
||||
const [, bMinor, bPatch] = b.split('.').map(Number);
|
||||
if (aMinor !== bMinor) return bMinor - aMinor;
|
||||
return bPatch - aPatch;
|
||||
});
|
||||
if (prevMajorVersions.length > 0) {
|
||||
extraPrevVersion = prevMajorVersions[0];
|
||||
}
|
||||
}
|
||||
|
||||
if (options.verbose && extraPrevVersion && publishTimes[extraPrevVersion]) {
|
||||
console.log(`📍 Using ${extraPrevVersion} as start boundary for time ranges`);
|
||||
}
|
||||
}
|
||||
|
||||
// Build time ranges for each version
|
||||
for (let i = 0; i < versionsToSearch.length; i++) {
|
||||
const version = versionsToSearch[i];
|
||||
|
||||
// Start time:
|
||||
// - For the first (newest) version, use the publish time of the version before it
|
||||
// - For middle versions, use the publish time of the next version in our list
|
||||
// - For the last (oldest) version, use the extra previous version we found
|
||||
let startTime = '2000-01-01T00:00:00Z'; // Default to old date
|
||||
|
||||
if (i === 0) {
|
||||
// First (newest) version - find its immediate predecessor
|
||||
const versionParts = version.split('.');
|
||||
const major = parseInt(versionParts[0]);
|
||||
const minor = parseInt(versionParts[1]);
|
||||
const patch = parseInt(versionParts[2]);
|
||||
|
||||
let prevVersion = '';
|
||||
if (patch > 0) {
|
||||
prevVersion = `${major}.${minor}.${patch - 1}`;
|
||||
} else if (minor > 0) {
|
||||
// Look for highest patch of previous minor
|
||||
const prevMinorPrefix = `${major}.${minor - 1}.`;
|
||||
const prevMinorVersions = Object.keys(publishTimes)
|
||||
.filter(v => v.startsWith(prevMinorPrefix))
|
||||
.sort((a, b) => {
|
||||
const aPatch = parseInt(a.split('.')[2] || '0');
|
||||
const bPatch = parseInt(b.split('.')[2] || '0');
|
||||
return bPatch - aPatch;
|
||||
});
|
||||
if (prevMinorVersions.length > 0) {
|
||||
prevVersion = prevMinorVersions[0];
|
||||
}
|
||||
}
|
||||
|
||||
if (publishTimes[prevVersion]) {
|
||||
startTime = publishTimes[prevVersion];
|
||||
}
|
||||
} else if (i < versionsToSearch.length - 1) {
|
||||
// Middle versions - use the next version in our list
|
||||
const prevVersionInList = versionsToSearch[i + 1];
|
||||
if (publishTimes[prevVersionInList]) {
|
||||
startTime = publishTimes[prevVersionInList];
|
||||
}
|
||||
} else {
|
||||
// Last (oldest) version - use the extra previous version
|
||||
if (extraPrevVersion && publishTimes[extraPrevVersion]) {
|
||||
startTime = publishTimes[extraPrevVersion];
|
||||
}
|
||||
}
|
||||
|
||||
// End time is this version's publish time (or now for unreleased)
|
||||
let endTime = publishTimes[version] || new Date().toISOString();
|
||||
|
||||
versionTimeRanges.push({ version, startTime, endTime });
|
||||
|
||||
if (options.verbose) {
|
||||
console.log(`📅 Version ${version}: ${new Date(startTime).toLocaleString()} - ${new Date(endTime).toLocaleString()}`);
|
||||
}
|
||||
}
|
||||
|
||||
// Always log what we're doing for single version
|
||||
if (historicalCount === 1) {
|
||||
const latestRange = versionTimeRanges[0];
|
||||
if (latestRange) {
|
||||
console.log(`📦 Using npm time range for ${latestRange.version}: ${new Date(latestRange.startTime).toLocaleString()} - ${new Date(latestRange.endTime).toLocaleString()}`);
|
||||
}
|
||||
}
|
||||
} catch (e) {
|
||||
console.log('❌ Could not fetch npm publish times. Cannot proceed without time ranges.');
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
console.log(`🔍 Searching memories for versions: ${versionsToSearch.join(', ')}`);
|
||||
console.log(`📦 Project: ${projectName}\n`);
|
||||
|
||||
// Phase 1: Search for version-related memories using MCP tools
|
||||
// ALWAYS use time range search - no other method
|
||||
const searchPrompt = versionTimeRanges.length > 0 ?
|
||||
`You are helping generate a changelog by searching for memories within specific time ranges for multiple versions.
|
||||
|
||||
PROJECT: ${projectName}
|
||||
VERSION TIME RANGES:
|
||||
${versionTimeRanges.map(r => `- Version ${r.version}: ${new Date(r.startTime).toLocaleDateString()} to ${new Date(r.endTime).toLocaleDateString()}`).join('\n')}
|
||||
|
||||
YOUR TASK:
|
||||
Use mcp__claude-mem__chroma_query_documents to search for memories for each version time range.
|
||||
|
||||
SEARCH STRATEGY:
|
||||
${versionTimeRanges.map(r => {
|
||||
const startDate = new Date(r.startTime);
|
||||
const endDate = new Date(r.endTime);
|
||||
|
||||
// Generate all date prefixes between start and end
|
||||
const datePrefixes: string[] = [];
|
||||
const currentDate = new Date(startDate);
|
||||
|
||||
while (currentDate <= endDate) {
|
||||
// Add day prefix like "2025-09-09"
|
||||
const dayPrefix = currentDate.toISOString().split('T')[0];
|
||||
datePrefixes.push(dayPrefix);
|
||||
currentDate.setDate(currentDate.getDate() + 1);
|
||||
}
|
||||
|
||||
return `
|
||||
Version ${r.version} (${new Date(r.startTime).toLocaleDateString()} to ${new Date(r.endTime).toLocaleDateString()}):
|
||||
1. Search for memories from these dates: ${datePrefixes.join(', ')}
|
||||
2. Make multiple calls to mcp__claude-mem__chroma_query_documents:
|
||||
- collection_name: "claude_memories"
|
||||
- query_texts: Include the project name AND date in each query:
|
||||
* "${projectName} ${datePrefixes[0]} feature"
|
||||
* "${projectName} ${datePrefixes[0]} fix"
|
||||
* "${projectName} ${datePrefixes[0]} change"
|
||||
* "${projectName} ${datePrefixes[0]} improvement"
|
||||
* "${projectName} ${datePrefixes[0]} refactor"
|
||||
- n_results: 50
|
||||
3. The date in the query text helps semantic search find memories from that day
|
||||
4. Assign memories to this version if their timestamp falls within:
|
||||
- Start: ${r.startTime}
|
||||
- End: ${r.endTime}`;
|
||||
}).join('\n')}
|
||||
|
||||
IMPORTANT:
|
||||
- Always include project name and date in query_texts for best results
|
||||
- Semantic search will naturally find memories near those dates
|
||||
- Group returned memories by version based on their timestamp metadata
|
||||
|
||||
Return a JSON object with this structure:
|
||||
{
|
||||
"memories": [
|
||||
{
|
||||
"version": "version_number",
|
||||
"text": "memory content",
|
||||
"metadata": {metadata object with timestamp},
|
||||
"relevance": "high/medium/low"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
Group memories by the version they belong to based on timestamp.
|
||||
Start searching now.` :
|
||||
`ERROR: No time ranges available. This should never happen.`;
|
||||
|
||||
if (versionTimeRanges.length === 0) {
|
||||
console.log('❌ No time ranges available. Cannot search memories.');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
if (options.verbose) {
|
||||
console.log('📝 Calling Claude to search memories...');
|
||||
}
|
||||
|
||||
// Call Claude with MCP tools to search memories
|
||||
const searchResponse = await query({
|
||||
prompt: searchPrompt,
|
||||
options: {
|
||||
allowedTools: [
|
||||
'mcp__claude-mem__chroma_query_documents',
|
||||
'mcp__claude-mem__chroma_get_documents'
|
||||
],
|
||||
pathToClaudeCodeExecutable: getClaudePath()
|
||||
}
|
||||
});
|
||||
|
||||
// Extract memories from response
|
||||
let memoriesJson = '';
|
||||
if (searchResponse && typeof searchResponse === 'object' && Symbol.asyncIterator in searchResponse) {
|
||||
for await (const message of searchResponse) {
|
||||
if (message?.type === 'assistant' && message?.message?.content) {
|
||||
const content = message.message.content;
|
||||
if (typeof content === 'string') {
|
||||
memoriesJson += content;
|
||||
} else if (Array.isArray(content)) {
|
||||
for (const block of content) {
|
||||
if (block.type === 'text' && block.text) {
|
||||
memoriesJson += block.text;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Parse memories
|
||||
let memories: MemorySearchResult[] = [];
|
||||
try {
|
||||
// Extract JSON from response (might be wrapped in markdown)
|
||||
const jsonMatch = memoriesJson.match(/```json\n([\s\S]*?)\n```/) ||
|
||||
memoriesJson.match(/\{[\s\S]*\}/);
|
||||
if (jsonMatch) {
|
||||
const parsed = JSON.parse(jsonMatch[1] || jsonMatch[0]);
|
||||
if (parsed.memories && Array.isArray(parsed.memories)) {
|
||||
memories = parsed.memories;
|
||||
}
|
||||
}
|
||||
} catch (e) {
|
||||
console.error('⚠️ Could not parse memory search results:', e);
|
||||
}
|
||||
|
||||
if (memories.length === 0) {
|
||||
console.log('\n⚠️ No version-related memories found for this version.');
|
||||
console.log(' This is normal for the first release or when no changes were tracked.');
|
||||
console.log(' Creating a placeholder changelog entry...');
|
||||
|
||||
// Create a minimal placeholder entry
|
||||
const placeholderEntry: ChangelogEntry = {
|
||||
version: versionsToSearch[0], // Use the first (current) version
|
||||
date: todayStr,
|
||||
type: 'Changed',
|
||||
description: 'Initial release or minor updates',
|
||||
timestamp: new Date().toISOString(),
|
||||
generatedAt: new Date().toISOString()
|
||||
};
|
||||
|
||||
// Save the placeholder entry
|
||||
if (!fs.existsSync(projectChangelogDir)) {
|
||||
fs.mkdirSync(projectChangelogDir, { recursive: true });
|
||||
}
|
||||
|
||||
const jsonlContent = JSON.stringify(placeholderEntry) + '\n';
|
||||
fs.appendFileSync(changelogJsonlPath, jsonlContent);
|
||||
|
||||
console.log(`✅ Created placeholder changelog entry for v${versionsToSearch[0]}`);
|
||||
|
||||
// Generate the CHANGELOG.md with the placeholder
|
||||
await updateChangelogFromJsonl(options);
|
||||
|
||||
return; // Exit successfully
|
||||
}
|
||||
|
||||
console.log(`✅ Found ${memories.length} version-related memories\n`);
|
||||
|
||||
// Get system date for accuracy
|
||||
const systemDate = execSync('date "+%Y-%m-%d %H:%M:%S %Z"').toString().trim();
|
||||
const todayStr = systemDate.split(' ')[0]; // YYYY-MM-DD format
|
||||
|
||||
// Phase 2: Generate changelog entries from memories
|
||||
const changelogPrompt = `Analyze these memories and generate changelog entries.
|
||||
|
||||
PROJECT: ${projectName}
|
||||
DATE: ${todayStr}
|
||||
|
||||
MEMORIES BY VERSION:
|
||||
${versionsToSearch.map(version => {
|
||||
const versionMemories = memories.filter(m => m.version === version);
|
||||
if (versionMemories.length === 0) return `### Version ${version}\nNo memories found.`;
|
||||
return `### Version ${version} (${versionMemories.length} memories):
|
||||
${versionMemories.map((m, i) => `${i + 1}. ${m.text}`).join('\n')}`;
|
||||
}).join('\n\n')}
|
||||
|
||||
INSTRUCTIONS:
|
||||
1. Extract concrete changes, fixes, and additions from the memories
|
||||
2. Categorize each change as: Added, Changed, Fixed, Removed, Deprecated, or Security
|
||||
3. Write clear, user-facing descriptions
|
||||
4. Start each entry with an action verb
|
||||
5. Focus on what matters to users, not internal implementation details
|
||||
|
||||
Return ONLY a JSON array with this structure:
|
||||
[
|
||||
{
|
||||
"version": "3.6.1",
|
||||
"type": "Added",
|
||||
"description": "New feature description"
|
||||
},
|
||||
{
|
||||
"version": "3.6.1",
|
||||
"type": "Fixed",
|
||||
"description": "Bug fix description"
|
||||
}
|
||||
]`;
|
||||
|
||||
console.log('🔄 Generating changelog entries...');
|
||||
|
||||
// Call Claude to generate changelog entries
|
||||
const changelogResponse = await query({
|
||||
prompt: changelogPrompt,
|
||||
options: {
|
||||
allowedTools: [],
|
||||
pathToClaudeCodeExecutable: getClaudePath()
|
||||
}
|
||||
});
|
||||
|
||||
// Extract JSON from response
|
||||
let entriesJson = '';
|
||||
if (changelogResponse && typeof changelogResponse === 'object' && Symbol.asyncIterator in changelogResponse) {
|
||||
for await (const message of changelogResponse) {
|
||||
if (message?.type === 'assistant' && message?.message?.content) {
|
||||
const content = message.message.content;
|
||||
if (typeof content === 'string') {
|
||||
entriesJson += content;
|
||||
} else if (Array.isArray(content)) {
|
||||
for (const block of content) {
|
||||
if (block.type === 'text' && block.text) {
|
||||
entriesJson += block.text;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Parse changelog entries
|
||||
let entries: ChangelogEntry[] = [];
|
||||
try {
|
||||
// Extract JSON (might be wrapped in markdown)
|
||||
const jsonMatch = entriesJson.match(/```json\n([\s\S]*?)\n```/) ||
|
||||
entriesJson.match(/\[[\s\S]*\]/);
|
||||
if (jsonMatch) {
|
||||
const parsed = JSON.parse(jsonMatch[1] || jsonMatch[0]);
|
||||
if (Array.isArray(parsed)) {
|
||||
const generatedAt = new Date().toISOString();
|
||||
entries = parsed.map(e => ({
|
||||
...e,
|
||||
date: todayStr,
|
||||
timestamp: e.timestamp || generatedAt, // Memory timestamp if available
|
||||
generatedAt: generatedAt // When this changelog was generated
|
||||
}));
|
||||
}
|
||||
}
|
||||
} catch (e) {
|
||||
console.error('⚠️ Could not parse changelog entries:', e);
|
||||
}
|
||||
|
||||
if (entries.length === 0) {
|
||||
console.log('⚠️ No changelog entries generated.');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
// Ensure project changelog directory exists
|
||||
if (!fs.existsSync(projectChangelogDir)) {
|
||||
fs.mkdirSync(projectChangelogDir, { recursive: true });
|
||||
}
|
||||
|
||||
// Save entries to project JSONL file
|
||||
console.log(`\n💾 Saving ${entries.length} changelog entries to ${path.basename(changelogJsonlPath)}`);
|
||||
|
||||
// When using --historical or --generate, remove old entries for the versions being regenerated
|
||||
if ((options.historical && historicalCount > 1) || options.generate) {
|
||||
let existingEntries: ChangelogEntry[] = [];
|
||||
if (fs.existsSync(changelogJsonlPath)) {
|
||||
const lines = fs.readFileSync(changelogJsonlPath, 'utf-8').split('\n').filter(l => l.trim());
|
||||
for (const line of lines) {
|
||||
try {
|
||||
const entry = JSON.parse(line);
|
||||
// Keep entries that are NOT in the versions we're regenerating
|
||||
if (!versionsToSearch.includes(entry.version)) {
|
||||
existingEntries.push(entry);
|
||||
}
|
||||
} catch (e) {
|
||||
// Skip invalid lines
|
||||
}
|
||||
}
|
||||
}
|
||||
// Rewrite the file with filtered entries plus new ones
|
||||
const allEntries = [...existingEntries, ...entries];
|
||||
const jsonlContent = allEntries.map(entry => JSON.stringify(entry)).join('\n') + '\n';
|
||||
fs.writeFileSync(changelogJsonlPath, jsonlContent);
|
||||
console.log(`🔄 Regenerated entries for versions: ${versionsToSearch.join(', ')}`);
|
||||
} else {
|
||||
// Append new entries to JSONL
|
||||
const jsonlContent = entries.map(entry => JSON.stringify(entry)).join('\n') + '\n';
|
||||
fs.appendFileSync(changelogJsonlPath, jsonlContent);
|
||||
}
|
||||
|
||||
// Now generate markdown from all JSONL entries
|
||||
console.log('\n📝 Generating CHANGELOG.md from entries...');
|
||||
|
||||
// Read all entries from JSONL
|
||||
let allEntries: ChangelogEntry[] = [];
|
||||
if (fs.existsSync(changelogJsonlPath)) {
|
||||
const lines = fs.readFileSync(changelogJsonlPath, 'utf-8').split('\n').filter(l => l.trim());
|
||||
for (const line of lines) {
|
||||
try {
|
||||
allEntries.push(JSON.parse(line));
|
||||
} catch (e) {
|
||||
// Skip invalid lines
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Group entries by version
|
||||
const entriesByVersion = new Map<string, ChangelogEntry[]>();
|
||||
for (const entry of allEntries) {
|
||||
if (!entriesByVersion.has(entry.version)) {
|
||||
entriesByVersion.set(entry.version, []);
|
||||
}
|
||||
entriesByVersion.get(entry.version)!.push(entry);
|
||||
}
|
||||
|
||||
// Generate markdown
|
||||
let markdown = '# Changelog\n\nAll notable changes to this project will be documented in this file.\n\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).\n\n';
|
||||
|
||||
// Sort versions in descending order
|
||||
const sortedVersions = Array.from(entriesByVersion.keys()).sort((a, b) => {
|
||||
const aParts = a.split('.').map(Number);
|
||||
const bParts = b.split('.').map(Number);
|
||||
for (let i = 0; i < 3; i++) {
|
||||
if (aParts[i] !== bParts[i]) return bParts[i] - aParts[i];
|
||||
}
|
||||
return 0;
|
||||
});
|
||||
|
||||
for (const version of sortedVersions) {
|
||||
const versionEntries = entriesByVersion.get(version)!;
|
||||
const date = versionEntries[0].date || todayStr;
|
||||
|
||||
markdown += `\n## [${version}] - ${date}\n\n`;
|
||||
|
||||
// Group by type
|
||||
const types: Array<ChangelogEntry['type']> = ['Added', 'Changed', 'Fixed', 'Removed', 'Deprecated', 'Security'];
|
||||
for (const type of types) {
|
||||
const typeEntries = versionEntries.filter(e => e.type === type);
|
||||
if (typeEntries.length > 0) {
|
||||
markdown += `### ${type}\n`;
|
||||
for (const entry of typeEntries) {
|
||||
markdown += `- ${entry.description}\n`;
|
||||
}
|
||||
markdown += '\n';
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Write the CHANGELOG.md
|
||||
const changelogPath = path.join(process.cwd(), 'CHANGELOG.md');
|
||||
fs.writeFileSync(changelogPath, markdown);
|
||||
|
||||
console.log(`✅ Generated CHANGELOG.md with ${allEntries.length} total entries across ${entriesByVersion.size} versions!`);
|
||||
|
||||
if (options.preview) {
|
||||
console.log('\n📄 Preview:\n');
|
||||
console.log(markdown.split('\n').slice(0, 30).join('\n'));
|
||||
if (markdown.split('\n').length > 30) {
|
||||
console.log('\n... (truncated for preview)');
|
||||
}
|
||||
}
|
||||
|
||||
} catch (error) {
|
||||
console.error('❌ Error generating changelog:', error instanceof Error ? error.message : error);
|
||||
if (error instanceof Error && error.stack) {
|
||||
console.error('Stack:', error.stack);
|
||||
}
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
async function updateChangelogFromJsonl(options: OptionValues): Promise<void> {
|
||||
try {
|
||||
// Get project name from package.json
|
||||
const packageJsonPath = path.join(process.cwd(), 'package.json');
|
||||
let projectName = 'unknown';
|
||||
if (fs.existsSync(packageJsonPath)) {
|
||||
try {
|
||||
const packageData = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
|
||||
projectName = packageData.name || path.basename(process.cwd());
|
||||
} catch (e) {
|
||||
projectName = path.basename(process.cwd());
|
||||
}
|
||||
}
|
||||
|
||||
const projectChangelogDir = path.join(
|
||||
process.env.HOME || process.env.USERPROFILE || '',
|
||||
'.claude-mem',
|
||||
'projects'
|
||||
);
|
||||
const changelogJsonlPath = path.join(projectChangelogDir, `${projectName}-changelog.jsonl`);
|
||||
|
||||
if (!fs.existsSync(changelogJsonlPath)) {
|
||||
console.log('❌ No changelog entries found. Generate some first with: claude-mem changelog');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
console.log('📝 Updating CHANGELOG.md from JSONL entries...');
|
||||
|
||||
// Read all entries from JSONL
|
||||
let allEntries: ChangelogEntry[] = [];
|
||||
const lines = fs.readFileSync(changelogJsonlPath, 'utf-8').split('\n').filter(l => l.trim());
|
||||
for (const line of lines) {
|
||||
try {
|
||||
allEntries.push(JSON.parse(line));
|
||||
} catch (e) {
|
||||
// Skip invalid lines
|
||||
}
|
||||
}
|
||||
|
||||
if (allEntries.length === 0) {
|
||||
console.log('❌ No valid entries found in JSONL file');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
// Group entries by version
|
||||
const entriesByVersion = new Map<string, ChangelogEntry[]>();
|
||||
for (const entry of allEntries) {
|
||||
if (!entriesByVersion.has(entry.version)) {
|
||||
entriesByVersion.set(entry.version, []);
|
||||
}
|
||||
entriesByVersion.get(entry.version)!.push(entry);
|
||||
}
|
||||
|
||||
// Generate markdown
|
||||
let markdown = '# Changelog\n\nAll notable changes to this project will be documented in this file.\n\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).\n\n';
|
||||
|
||||
// Sort versions in descending order
|
||||
const sortedVersions = Array.from(entriesByVersion.keys()).sort((a, b) => {
|
||||
const aParts = a.split('.').map(Number);
|
||||
const bParts = b.split('.').map(Number);
|
||||
for (let i = 0; i < 3; i++) {
|
||||
if (aParts[i] !== bParts[i]) return bParts[i] - aParts[i];
|
||||
}
|
||||
return 0;
|
||||
});
|
||||
|
||||
for (const version of sortedVersions) {
|
||||
const versionEntries = entriesByVersion.get(version)!;
|
||||
const date = versionEntries[0].date;
|
||||
|
||||
markdown += `\n## [${version}] - ${date}\n\n`;
|
||||
|
||||
// Group by type
|
||||
const types: Array<ChangelogEntry['type']> = ['Added', 'Changed', 'Fixed', 'Removed', 'Deprecated', 'Security'];
|
||||
for (const type of types) {
|
||||
const typeEntries = versionEntries.filter(e => e.type === type);
|
||||
if (typeEntries.length > 0) {
|
||||
markdown += `### ${type}\n`;
|
||||
for (const entry of typeEntries) {
|
||||
markdown += `- ${entry.description}\n`;
|
||||
}
|
||||
markdown += '\n';
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Write the CHANGELOG.md
|
||||
const changelogPath = path.join(process.cwd(), 'CHANGELOG.md');
|
||||
fs.writeFileSync(changelogPath, markdown);
|
||||
|
||||
console.log(`✅ Updated CHANGELOG.md with ${allEntries.length} entries across ${entriesByVersion.size} versions!`);
|
||||
|
||||
if (options.preview) {
|
||||
console.log('\n📄 Preview:\n');
|
||||
console.log(markdown.split('\n').slice(0, 30).join('\n'));
|
||||
if (markdown.split('\n').length > 30) {
|
||||
console.log('\n... (truncated for preview)');
|
||||
}
|
||||
}
|
||||
} catch (error) {
|
||||
console.error('❌ Error updating changelog:', error instanceof Error ? error.message : error);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,43 @@
|
||||
import { OptionValues } from 'commander';
|
||||
import { basename, dirname } from 'path';
|
||||
import {
|
||||
createLoadingMessage,
|
||||
createCompletionMessage,
|
||||
createOperationSummary,
|
||||
createUserFriendlyError
|
||||
} from '../prompts/templates/context/ContextTemplates.js';
|
||||
|
||||
export async function compress(transcript?: string, options: OptionValues = {}): Promise<void> {
|
||||
console.log(createLoadingMessage('compressing'));
|
||||
|
||||
if (!transcript) {
|
||||
console.log(createUserFriendlyError('Compression', 'No transcript file provided', 'Please provide a path to a transcript file'));
|
||||
return;
|
||||
}
|
||||
|
||||
try {
|
||||
const startTime = Date.now();
|
||||
|
||||
// Import and run compression
|
||||
const { TranscriptCompressor } = await import('../core/compression/TranscriptCompressor.js');
|
||||
const compressor = new TranscriptCompressor({
|
||||
verbose: options.verbose || false
|
||||
});
|
||||
|
||||
const sessionId = options.sessionId || basename(transcript, '.jsonl');
|
||||
const archivePath = await compressor.compress(transcript, sessionId);
|
||||
|
||||
const duration = Date.now() - startTime;
|
||||
|
||||
console.log(createCompletionMessage('Compression', undefined, `Session archived as ${basename(archivePath)}`));
|
||||
console.log(createOperationSummary('compress', { count: 1, duration, details: `Session: ${sessionId}` }));
|
||||
} catch (error) {
|
||||
const errorMessage = error instanceof Error ? error.message : String(error);
|
||||
console.log(createUserFriendlyError(
|
||||
'Compression',
|
||||
errorMessage,
|
||||
'Check that the transcript file exists and you have write permissions'
|
||||
));
|
||||
throw error; // Re-throw to maintain existing error handling behavior
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,146 @@
|
||||
/**
|
||||
* Hook command handlers for binary distribution
|
||||
* These execute the actual hook logic embedded in the binary
|
||||
*/
|
||||
|
||||
import { basename, sep } from 'path';
|
||||
import { compress } from './compress.js';
|
||||
import { loadContext } from './load-context.js';
|
||||
|
||||
/**
|
||||
* Pre-compact hook handler
|
||||
* Runs compression on the Claude Code transcript
|
||||
*/
|
||||
export async function preCompactHook(): Promise<void> {
|
||||
try {
|
||||
// Read hook data from stdin (Claude Code sends JSON)
|
||||
let inputData = '';
|
||||
|
||||
// Set up stdin to read data
|
||||
process.stdin.setEncoding('utf8');
|
||||
|
||||
// Collect all input data
|
||||
for await (const chunk of process.stdin) {
|
||||
inputData += chunk;
|
||||
}
|
||||
|
||||
// Parse the JSON input
|
||||
let transcriptPath: string | undefined;
|
||||
|
||||
if (inputData) {
|
||||
try {
|
||||
const hookData = JSON.parse(inputData);
|
||||
transcriptPath = hookData.transcript_path;
|
||||
} catch (parseError) {
|
||||
// If JSON parsing fails, treat the input as a direct path
|
||||
transcriptPath = inputData.trim();
|
||||
}
|
||||
}
|
||||
|
||||
// Fallback to environment variable or command line argument
|
||||
if (!transcriptPath) {
|
||||
transcriptPath = process.env.TRANSCRIPT_PATH || process.argv[2];
|
||||
}
|
||||
|
||||
if (!transcriptPath) {
|
||||
console.log('🗜️ Compressing session transcript...');
|
||||
console.log('❌ No transcript path provided to pre-compact hook');
|
||||
console.log('Hook data received:', inputData || 'none');
|
||||
console.log('Environment TRANSCRIPT_PATH:', process.env.TRANSCRIPT_PATH || 'not set');
|
||||
console.log('Command line args:', process.argv.slice(2));
|
||||
return;
|
||||
}
|
||||
|
||||
// Run compression with the transcript path
|
||||
await compress(transcriptPath, { dryRun: false });
|
||||
} catch (error: any) {
|
||||
console.error('Pre-compact hook failed:', error.message);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Session-start hook handler
|
||||
* Loads context for the new session
|
||||
*/
|
||||
export async function sessionStartHook(): Promise<void> {
|
||||
try {
|
||||
// Read hook data from stdin (Claude Code sends JSON)
|
||||
let inputData = '';
|
||||
|
||||
// Set up stdin to read data
|
||||
process.stdin.setEncoding('utf8');
|
||||
|
||||
// Collect all input data
|
||||
for await (const chunk of process.stdin) {
|
||||
inputData += chunk;
|
||||
}
|
||||
|
||||
// Parse the JSON input to get the current working directory
|
||||
let project: string | undefined;
|
||||
|
||||
if (inputData) {
|
||||
try {
|
||||
const hookData = JSON.parse(inputData);
|
||||
// Extract project name from cwd if provided
|
||||
if (hookData.cwd) {
|
||||
project = basename(hookData.cwd);
|
||||
}
|
||||
} catch (parseError) {
|
||||
// If JSON parsing fails, continue without project filtering
|
||||
console.error('Failed to parse session-start hook data:', parseError);
|
||||
}
|
||||
}
|
||||
|
||||
// If no project from hook data, try to get from current working directory
|
||||
if (!project) {
|
||||
project = basename(process.cwd());
|
||||
}
|
||||
|
||||
// Load context with session-start format and project filtering
|
||||
await loadContext({ format: 'session-start', count: '10', project });
|
||||
} catch (error: any) {
|
||||
console.error('Session-start hook failed:', error.message);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Session-end hook handler
|
||||
* Compresses session transcript when ending with /clear
|
||||
*/
|
||||
export async function sessionEndHook(): Promise<void> {
|
||||
try {
|
||||
// Read hook data from stdin (Claude Code sends JSON)
|
||||
let inputData = '';
|
||||
|
||||
// Set up stdin to read data
|
||||
process.stdin.setEncoding('utf8');
|
||||
|
||||
// Collect all input data
|
||||
for await (const chunk of process.stdin) {
|
||||
inputData += chunk;
|
||||
}
|
||||
|
||||
// Parse the JSON input to check the reason for session end
|
||||
if (inputData) {
|
||||
try {
|
||||
const hookData = JSON.parse(inputData);
|
||||
|
||||
// If reason is "clear", compress the session transcript before it's deleted
|
||||
if (hookData.reason === 'clear' && hookData.transcript_path) {
|
||||
console.log('🗜️ Compressing current session before /clear...');
|
||||
await compress(hookData.transcript_path, { dryRun: false });
|
||||
}
|
||||
} catch (parseError) {
|
||||
// If JSON parsing fails, log but don't fail the hook
|
||||
console.error('Failed to parse hook data:', parseError);
|
||||
}
|
||||
}
|
||||
|
||||
console.log('Session ended successfully');
|
||||
} catch (error: any) {
|
||||
console.error('Session-end hook failed:', error.message);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,541 @@
|
||||
#!/usr/bin/env node
|
||||
import * as p from '@clack/prompts';
|
||||
import path from 'path';
|
||||
import fs from 'fs';
|
||||
import os from 'os';
|
||||
import chalk from 'chalk';
|
||||
import { TranscriptCompressor } from '../core/compression/TranscriptCompressor.js';
|
||||
import { TitleGenerator, TitleGenerationRequest } from '../core/titles/TitleGenerator.js';
|
||||
|
||||
interface ConversationMetadata {
|
||||
sessionId: string;
|
||||
timestamp: string;
|
||||
messageCount: number;
|
||||
branch?: string;
|
||||
cwd: string;
|
||||
fileSize: number;
|
||||
}
|
||||
|
||||
interface ConversationItem extends ConversationMetadata {
|
||||
filePath: string;
|
||||
projectName: string;
|
||||
parsedDate: Date;
|
||||
relativeDate: string;
|
||||
}
|
||||
|
||||
function formatFileSize(bytes: number): string {
|
||||
if (bytes < 1024) return `${bytes}B`;
|
||||
if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
|
||||
return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
|
||||
}
|
||||
|
||||
function formatRelativeDate(date: Date): string {
|
||||
const now = new Date();
|
||||
const diffMs = now.getTime() - date.getTime();
|
||||
const diffMins = Math.floor(diffMs / 60000);
|
||||
const diffHours = Math.floor(diffMs / 3600000);
|
||||
const diffDays = Math.floor(diffMs / 86400000);
|
||||
|
||||
if (diffMins < 1) return 'just now';
|
||||
if (diffMins < 60) return `${diffMins}m ago`;
|
||||
if (diffHours < 24) return `${diffHours}h ago`;
|
||||
if (diffDays < 7) return `${diffDays}d ago`;
|
||||
if (diffDays < 30) return `${Math.floor(diffDays / 7)}w ago`;
|
||||
if (diffDays < 365) return `${Math.floor(diffDays / 30)}mo ago`;
|
||||
return `${Math.floor(diffDays / 365)}y ago`;
|
||||
}
|
||||
|
||||
function parseTimestamp(timestamp: string, fallbackPath: string): Date {
|
||||
try {
|
||||
const parsed = new Date(timestamp);
|
||||
if (!isNaN(parsed.getTime())) return parsed;
|
||||
} catch {}
|
||||
|
||||
// Fallback: try to extract from filename
|
||||
const match = fallbackPath.match(/(\d{4})-(\d{2})-(\d{2})_(\d{2})-(\d{2})-(\d{2})/);
|
||||
if (match) {
|
||||
const [_, year, month, day, hour, minute, second] = match;
|
||||
return new Date(
|
||||
parseInt(year),
|
||||
parseInt(month) - 1,
|
||||
parseInt(day),
|
||||
parseInt(hour),
|
||||
parseInt(minute),
|
||||
parseInt(second)
|
||||
);
|
||||
}
|
||||
|
||||
// Last resort: file stats
|
||||
const stats = fs.statSync(fallbackPath);
|
||||
return stats.mtime;
|
||||
}
|
||||
|
||||
function extractFirstUserMessage(filePath: string): string {
|
||||
try {
|
||||
const content = fs.readFileSync(filePath, 'utf-8');
|
||||
const lines = content.trim().split('\n').filter(Boolean);
|
||||
|
||||
for (const line of lines) {
|
||||
try {
|
||||
const message = JSON.parse(line);
|
||||
if (message.type === 'user' && message.message?.content) {
|
||||
const messageContent = message.message.content;
|
||||
if (Array.isArray(messageContent)) {
|
||||
const textContent = messageContent
|
||||
.filter(item => item.type === 'text')
|
||||
.map(item => item.text)
|
||||
.join(' ');
|
||||
if (textContent.trim()) return textContent.trim();
|
||||
} else if (typeof messageContent === 'string') {
|
||||
return messageContent.trim();
|
||||
}
|
||||
}
|
||||
} catch {}
|
||||
}
|
||||
|
||||
return 'Conversation'; // Fallback
|
||||
} catch {
|
||||
return 'Conversation'; // Fallback
|
||||
}
|
||||
}
|
||||
|
||||
async function loadImportedSessions(): Promise<Set<string>> {
|
||||
const importedIds = new Set<string>();
|
||||
const indexPath = path.join(os.homedir(), '.claude-mem', 'claude-mem-index.jsonl');
|
||||
|
||||
if (!fs.existsSync(indexPath)) return importedIds;
|
||||
|
||||
const content = fs.readFileSync(indexPath, 'utf-8');
|
||||
const lines = content.trim().split('\n').filter(Boolean);
|
||||
|
||||
for (const line of lines) {
|
||||
try {
|
||||
const entry = JSON.parse(line);
|
||||
// Check both session_id (from index) and sessionId (legacy)
|
||||
if (entry.session_id) {
|
||||
importedIds.add(entry.session_id);
|
||||
} else if (entry.sessionId) {
|
||||
importedIds.add(entry.sessionId);
|
||||
}
|
||||
} catch {}
|
||||
}
|
||||
|
||||
return importedIds;
|
||||
}
|
||||
|
||||
async function scanConversations(): Promise<{ conversations: ConversationItem[]; skippedCount: number }> {
|
||||
const claudeDir = path.join(os.homedir(), '.claude', 'projects');
|
||||
|
||||
if (!fs.existsSync(claudeDir)) {
|
||||
return { conversations: [], skippedCount: 0 };
|
||||
}
|
||||
|
||||
const projects = fs.readdirSync(claudeDir)
|
||||
.filter(dir => fs.statSync(path.join(claudeDir, dir)).isDirectory());
|
||||
|
||||
const conversations: ConversationItem[] = [];
|
||||
const importedSessionIds = await loadImportedSessions();
|
||||
let skippedCount = 0;
|
||||
|
||||
for (const project of projects) {
|
||||
const projectDir = path.join(claudeDir, project);
|
||||
const files = fs.readdirSync(projectDir)
|
||||
.filter(file => file.endsWith('.jsonl'))
|
||||
.map(file => path.join(projectDir, file));
|
||||
|
||||
for (const filePath of files) {
|
||||
try {
|
||||
const content = fs.readFileSync(filePath, 'utf-8');
|
||||
const lines = content.trim().split('\n').filter(Boolean);
|
||||
|
||||
// Parse first line for metadata
|
||||
const firstLine = JSON.parse(lines[0]);
|
||||
const messageCount = lines.length;
|
||||
const stats = fs.statSync(filePath);
|
||||
const fileSize = stats.size;
|
||||
|
||||
const metadata: ConversationMetadata = {
|
||||
sessionId: firstLine.sessionId || path.basename(filePath, '.jsonl'),
|
||||
timestamp: firstLine.timestamp || stats.mtime.toISOString(),
|
||||
messageCount,
|
||||
branch: firstLine.branch,
|
||||
cwd: firstLine.cwd || projectDir,
|
||||
fileSize
|
||||
};
|
||||
|
||||
// Skip if already imported
|
||||
if (importedSessionIds.has(metadata.sessionId)) {
|
||||
skippedCount++;
|
||||
continue;
|
||||
}
|
||||
|
||||
const projectName = path.basename(path.dirname(filePath));
|
||||
const parsedDate = parseTimestamp(metadata.timestamp, filePath);
|
||||
const relativeDate = formatRelativeDate(parsedDate);
|
||||
|
||||
conversations.push({
|
||||
filePath,
|
||||
...metadata,
|
||||
projectName,
|
||||
parsedDate,
|
||||
relativeDate
|
||||
});
|
||||
} catch {}
|
||||
}
|
||||
}
|
||||
|
||||
return { conversations, skippedCount };
|
||||
}
|
||||
|
||||
export async function importHistory(options: { verbose?: boolean; multi?: boolean } = {}) {
|
||||
console.clear();
|
||||
|
||||
p.intro(chalk.bgCyan.black(' CLAUDE-MEM IMPORT '));
|
||||
|
||||
const s = p.spinner();
|
||||
s.start('Scanning conversation history');
|
||||
|
||||
const { conversations, skippedCount } = await scanConversations();
|
||||
|
||||
if (conversations.length === 0) {
|
||||
s.stop('No new conversations found');
|
||||
const message = skippedCount > 0
|
||||
? `All ${skippedCount} conversation${skippedCount === 1 ? ' is' : 's are'} already imported.`
|
||||
: 'No conversations found.';
|
||||
p.outro(chalk.yellow(message));
|
||||
return;
|
||||
}
|
||||
|
||||
// Sort by date (newest first)
|
||||
conversations.sort((a, b) => b.parsedDate.getTime() - a.parsedDate.getTime());
|
||||
|
||||
const statusMessage = skippedCount > 0
|
||||
? `Found ${conversations.length} new conversation${conversations.length === 1 ? '' : 's'} (${skippedCount} already imported)`
|
||||
: `Found ${conversations.length} new conversation${conversations.length === 1 ? '' : 's'}`;
|
||||
s.stop(statusMessage);
|
||||
|
||||
// Group conversations by project for better organization
|
||||
const projectGroups = conversations.reduce((acc, conv) => {
|
||||
if (!acc[conv.projectName]) acc[conv.projectName] = [];
|
||||
acc[conv.projectName].push(conv);
|
||||
return acc;
|
||||
}, {} as Record<string, ConversationItem[]>);
|
||||
|
||||
// Create selection options
|
||||
const importMode = await p.select({
|
||||
message: 'How would you like to import?',
|
||||
options: [
|
||||
{ value: 'browse', label: 'Browse by Project', hint: 'Select project then conversations' },
|
||||
{ value: 'project', label: 'Import Entire Project', hint: 'Select project and import all conversations' },
|
||||
{ value: 'recent', label: 'Recent Conversations', hint: 'Import most recent across all projects' },
|
||||
{ value: 'search', label: 'Search', hint: 'Search for specific conversations' }
|
||||
]
|
||||
});
|
||||
|
||||
if (p.isCancel(importMode)) {
|
||||
p.cancel('Import cancelled');
|
||||
return;
|
||||
}
|
||||
|
||||
let selectedConversations: ConversationItem[] = [];
|
||||
|
||||
if (importMode === 'browse') {
|
||||
// Project selection
|
||||
const projectOptions = Object.entries(projectGroups)
|
||||
.sort((a, b) => b[1][0].parsedDate.getTime() - a[1][0].parsedDate.getTime())
|
||||
.map(([project, convs]) => ({
|
||||
value: project,
|
||||
label: project,
|
||||
hint: `${convs.length} conversation${convs.length === 1 ? '' : 's'}, latest: ${convs[0].relativeDate}`
|
||||
}));
|
||||
|
||||
const selectedProject = await p.select({
|
||||
message: 'Select a project',
|
||||
options: projectOptions
|
||||
});
|
||||
|
||||
if (p.isCancel(selectedProject)) {
|
||||
p.cancel('Import cancelled');
|
||||
return;
|
||||
}
|
||||
|
||||
const projectConvs = projectGroups[selectedProject as string];
|
||||
|
||||
// Ask about title generation
|
||||
const generateTitles = await p.confirm({
|
||||
message: 'Would you like to generate titles for easier browsing?',
|
||||
initialValue: false
|
||||
});
|
||||
|
||||
if (p.isCancel(generateTitles)) {
|
||||
p.cancel('Import cancelled');
|
||||
return;
|
||||
}
|
||||
|
||||
if (generateTitles) {
|
||||
await processTitleGeneration(projectConvs, selectedProject as string);
|
||||
}
|
||||
|
||||
// Conversation selection within project
|
||||
const titleGenerator = new TitleGenerator();
|
||||
const convOptions = projectConvs.map(conv => {
|
||||
const title = titleGenerator.getTitleForSession(conv.sessionId);
|
||||
const displayTitle = title ? `"${title}" • ` : '';
|
||||
return {
|
||||
value: conv.sessionId,
|
||||
label: `${displayTitle}${conv.relativeDate} • ${conv.messageCount} messages • ${formatFileSize(conv.fileSize)}`,
|
||||
hint: conv.branch ? `branch: ${conv.branch}` : undefined
|
||||
};
|
||||
});
|
||||
|
||||
if (options.multi) {
|
||||
const selected = await p.multiselect({
|
||||
message: `Select conversations from ${selectedProject} (Space to select, Enter to confirm)`,
|
||||
options: convOptions,
|
||||
required: false
|
||||
});
|
||||
|
||||
if (p.isCancel(selected)) {
|
||||
p.cancel('Import cancelled');
|
||||
return;
|
||||
}
|
||||
|
||||
const selectedIds = selected as string[];
|
||||
selectedConversations = projectConvs.filter(c => selectedIds.includes(c.sessionId));
|
||||
} else {
|
||||
// Single select with continuous import
|
||||
let continueImporting = true;
|
||||
const importedInSession = new Set<string>();
|
||||
|
||||
while (continueImporting && projectConvs.length > importedInSession.size) {
|
||||
const availableConvs = projectConvs.filter(c => !importedInSession.has(c.sessionId));
|
||||
|
||||
if (availableConvs.length === 0) break;
|
||||
|
||||
const titleGenerator = new TitleGenerator();
|
||||
const convOptions = availableConvs.map(conv => {
|
||||
const title = titleGenerator.getTitleForSession(conv.sessionId);
|
||||
const displayTitle = title ? `"${title}" • ` : '';
|
||||
return {
|
||||
value: conv.sessionId,
|
||||
label: `${displayTitle}${conv.relativeDate} • ${conv.messageCount} messages • ${formatFileSize(conv.fileSize)}`,
|
||||
hint: conv.branch ? `branch: ${conv.branch}` : undefined
|
||||
};
|
||||
});
|
||||
|
||||
const selected = await p.select({
|
||||
message: `Select a conversation (${importedInSession.size}/${projectConvs.length} imported)`,
|
||||
options: [
|
||||
...convOptions,
|
||||
{ value: 'done', label: '✅ Done importing', hint: 'Exit import mode' }
|
||||
]
|
||||
});
|
||||
|
||||
if (p.isCancel(selected) || selected === 'done') {
|
||||
continueImporting = false;
|
||||
break;
|
||||
}
|
||||
|
||||
const conv = availableConvs.find(c => c.sessionId === selected);
|
||||
if (conv) {
|
||||
selectedConversations = [conv];
|
||||
await processImport(selectedConversations, options.verbose);
|
||||
importedInSession.add(conv.sessionId);
|
||||
}
|
||||
}
|
||||
|
||||
if (importedInSession.size > 0) {
|
||||
p.outro(chalk.green(`✅ Imported ${importedInSession.size} conversation${importedInSession.size === 1 ? '' : 's'}`));
|
||||
} else {
|
||||
p.outro(chalk.yellow('No conversations imported'));
|
||||
}
|
||||
return;
|
||||
}
|
||||
|
||||
} else if (importMode === 'project') {
|
||||
// Project selection for importing entire project
|
||||
const projectOptions = Object.entries(projectGroups)
|
||||
.sort((a, b) => b[1][0].parsedDate.getTime() - a[1][0].parsedDate.getTime())
|
||||
.map(([project, convs]) => ({
|
||||
value: project,
|
||||
label: project,
|
||||
hint: `${convs.length} conversation${convs.length === 1 ? '' : 's'}, latest: ${convs[0].relativeDate}`
|
||||
}));
|
||||
|
||||
const selectedProject = await p.select({
|
||||
message: 'Select a project to import all conversations',
|
||||
options: projectOptions
|
||||
});
|
||||
|
||||
if (p.isCancel(selectedProject)) {
|
||||
p.cancel('Import cancelled');
|
||||
return;
|
||||
}
|
||||
|
||||
const projectConvs = projectGroups[selectedProject as string];
|
||||
|
||||
// Ask about title generation
|
||||
const generateTitles = await p.confirm({
|
||||
message: 'Would you like to generate titles for easier browsing?',
|
||||
initialValue: false
|
||||
});
|
||||
|
||||
if (p.isCancel(generateTitles)) {
|
||||
p.cancel('Import cancelled');
|
||||
return;
|
||||
}
|
||||
|
||||
if (generateTitles) {
|
||||
await processTitleGeneration(projectConvs, selectedProject as string);
|
||||
}
|
||||
|
||||
const confirm = await p.confirm({
|
||||
message: `Import all ${projectConvs.length} conversation${projectConvs.length === 1 ? '' : 's'} from ${selectedProject}?`
|
||||
});
|
||||
|
||||
if (p.isCancel(confirm) || !confirm) {
|
||||
p.cancel('Import cancelled');
|
||||
return;
|
||||
}
|
||||
|
||||
selectedConversations = projectConvs;
|
||||
|
||||
} else if (importMode === 'recent') {
|
||||
const limit = await p.text({
|
||||
message: 'How many recent conversations?',
|
||||
placeholder: '10',
|
||||
initialValue: '10',
|
||||
validate: (value) => {
|
||||
const num = parseInt(value);
|
||||
if (isNaN(num) || num < 1) return 'Please enter a valid number';
|
||||
if (num > conversations.length) return `Only ${conversations.length} available`;
|
||||
}
|
||||
});
|
||||
|
||||
if (p.isCancel(limit)) {
|
||||
p.cancel('Import cancelled');
|
||||
return;
|
||||
}
|
||||
|
||||
const count = parseInt(limit as string);
|
||||
selectedConversations = conversations.slice(0, count);
|
||||
|
||||
} else if (importMode === 'search') {
|
||||
const searchTerm = await p.text({
|
||||
message: 'Search conversations (project name or session ID)',
|
||||
placeholder: 'Enter search term'
|
||||
});
|
||||
|
||||
if (p.isCancel(searchTerm)) {
|
||||
p.cancel('Import cancelled');
|
||||
return;
|
||||
}
|
||||
|
||||
const term = (searchTerm as string).toLowerCase();
|
||||
const matches = conversations.filter(c =>
|
||||
c.projectName.toLowerCase().includes(term) ||
|
||||
c.sessionId.toLowerCase().includes(term) ||
|
||||
(c.branch && c.branch.toLowerCase().includes(term))
|
||||
);
|
||||
|
||||
if (matches.length === 0) {
|
||||
p.outro(chalk.yellow('No matching conversations found'));
|
||||
return;
|
||||
}
|
||||
|
||||
const titleGenerator = new TitleGenerator();
|
||||
const matchOptions = matches.map(conv => {
|
||||
const title = titleGenerator.getTitleForSession(conv.sessionId);
|
||||
const displayTitle = title ? `"${title}" • ` : '';
|
||||
return {
|
||||
value: conv.sessionId,
|
||||
label: `${displayTitle}${conv.projectName} • ${conv.relativeDate} • ${conv.messageCount} msgs`,
|
||||
hint: formatFileSize(conv.fileSize)
|
||||
};
|
||||
});
|
||||
|
||||
const selected = await p.multiselect({
|
||||
message: `Found ${matches.length} matches. Select to import:`,
|
||||
options: matchOptions,
|
||||
required: false
|
||||
});
|
||||
|
||||
if (p.isCancel(selected)) {
|
||||
p.cancel('Import cancelled');
|
||||
return;
|
||||
}
|
||||
|
||||
const selectedIds = selected as string[];
|
||||
selectedConversations = matches.filter(c => selectedIds.includes(c.sessionId));
|
||||
}
|
||||
|
||||
// Process the import
|
||||
if (selectedConversations.length > 0) {
|
||||
await processImport(selectedConversations, options.verbose);
|
||||
p.outro(chalk.green(`✅ Successfully imported ${selectedConversations.length} conversation${selectedConversations.length === 1 ? '' : 's'}`));
|
||||
} else {
|
||||
p.outro(chalk.yellow('No conversations selected for import'));
|
||||
}
|
||||
}
|
||||
|
||||
async function processTitleGeneration(conversations: ConversationItem[], projectName: string) {
|
||||
const titleGenerator = new TitleGenerator();
|
||||
const existingTitles = titleGenerator.getExistingTitles();
|
||||
|
||||
// Filter conversations that don't have titles yet
|
||||
const conversationsNeedingTitles = conversations.filter(conv => !existingTitles.has(conv.sessionId));
|
||||
|
||||
if (conversationsNeedingTitles.length === 0) {
|
||||
p.note('All conversations already have titles!', 'Title Generation');
|
||||
return;
|
||||
}
|
||||
|
||||
const s = p.spinner();
|
||||
s.start(`Generating titles for ${conversationsNeedingTitles.length} conversations...`);
|
||||
|
||||
const requests: TitleGenerationRequest[] = conversationsNeedingTitles.map(conv => ({
|
||||
sessionId: conv.sessionId,
|
||||
projectName: projectName,
|
||||
firstMessage: extractFirstUserMessage(conv.filePath)
|
||||
}));
|
||||
|
||||
try {
|
||||
await titleGenerator.batchGenerateTitles(requests);
|
||||
s.stop(`✅ Generated ${conversationsNeedingTitles.length} titles`);
|
||||
} catch (error) {
|
||||
s.stop(`❌ Failed to generate titles`);
|
||||
console.error(chalk.red(`Error: ${error}`));
|
||||
}
|
||||
}
|
||||
|
||||
async function processImport(conversations: ConversationItem[], verbose?: boolean) {
|
||||
const s = p.spinner();
|
||||
|
||||
for (let i = 0; i < conversations.length; i++) {
|
||||
const conv = conversations[i];
|
||||
const progress = conversations.length > 1 ? `[${i + 1}/${conversations.length}] ` : '';
|
||||
|
||||
s.start(`${progress}Importing ${conv.projectName} (${conv.relativeDate})`);
|
||||
|
||||
try {
|
||||
// Extract project name from the conversation's cwd field
|
||||
const projectName = path.basename(conv.cwd);
|
||||
|
||||
// Use TranscriptCompressor to process
|
||||
const compressor = new TranscriptCompressor();
|
||||
await compressor.compress(conv.filePath, conv.sessionId, projectName);
|
||||
|
||||
s.stop(`${progress}Imported ${conv.projectName} (${conv.messageCount} messages)`);
|
||||
|
||||
if (verbose) {
|
||||
p.note(`Session: ${conv.sessionId}\nSize: ${formatFileSize(conv.fileSize)}\nBranch: ${conv.branch || 'main'}`, 'Details');
|
||||
}
|
||||
|
||||
} catch (error) {
|
||||
s.stop(`${progress}Failed to import ${conv.projectName}`);
|
||||
if (verbose) {
|
||||
console.error(chalk.red(`Error: ${error}`));
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,205 @@
|
||||
import { OptionValues } from 'commander';
|
||||
import fs from 'fs';
|
||||
import { join } from 'path';
|
||||
import { PathDiscovery } from '../services/path-discovery.js';
|
||||
import {
|
||||
createCompletionMessage,
|
||||
createContextualError,
|
||||
createUserFriendlyError,
|
||||
formatTimeAgo,
|
||||
outputSessionStartContent
|
||||
} from '../prompts/templates/context/ContextTemplates.js';
|
||||
|
||||
interface TrashStatus {
|
||||
folderCount: number;
|
||||
fileCount: number;
|
||||
totalSize: number;
|
||||
isEmpty: boolean;
|
||||
}
|
||||
|
||||
function buildProjectMatcher(projectName: string): (value?: string) => boolean {
|
||||
const aliases = new Set<string>();
|
||||
aliases.add(projectName);
|
||||
aliases.add(projectName.replace(/-/g, '_'));
|
||||
aliases.add(projectName.replace(/_/g, '-'));
|
||||
return (value?: string) => !!value && aliases.has(value);
|
||||
}
|
||||
|
||||
function formatSize(bytes: number): string {
|
||||
if (bytes === 0) return '0 B';
|
||||
const k = 1024;
|
||||
const sizes = ['B', 'KB', 'MB', 'GB'];
|
||||
const i = Math.floor(Math.log(bytes) / Math.log(k));
|
||||
return parseFloat((bytes / Math.pow(k, i)).toFixed(1)) + ' ' + sizes[i];
|
||||
}
|
||||
|
||||
function getTrashStatus(): TrashStatus {
|
||||
const trashDir = PathDiscovery.getInstance().getTrashDirectory();
|
||||
|
||||
if (!fs.existsSync(trashDir)) {
|
||||
return { folderCount: 0, fileCount: 0, totalSize: 0, isEmpty: true };
|
||||
}
|
||||
|
||||
const items = fs.readdirSync(trashDir);
|
||||
if (items.length === 0) {
|
||||
return { folderCount: 0, fileCount: 0, totalSize: 0, isEmpty: true };
|
||||
}
|
||||
|
||||
let folderCount = 0;
|
||||
let fileCount = 0;
|
||||
let totalSize = 0;
|
||||
|
||||
for (const item of items) {
|
||||
const itemPath = join(trashDir, item);
|
||||
const stats = fs.statSync(itemPath);
|
||||
|
||||
if (stats.isDirectory()) {
|
||||
folderCount++;
|
||||
} else {
|
||||
fileCount++;
|
||||
}
|
||||
|
||||
totalSize += stats.size;
|
||||
}
|
||||
|
||||
return { folderCount, fileCount, totalSize, isEmpty: false };
|
||||
}
|
||||
|
||||
export async function loadContext(options: OptionValues = {}): Promise<void> {
|
||||
const pathDiscovery = PathDiscovery.getInstance();
|
||||
const indexPath = pathDiscovery.getIndexPath();
|
||||
|
||||
try {
|
||||
// Check if index file exists
|
||||
if (!fs.existsSync(indexPath)) {
|
||||
if (options.format === 'session-start') {
|
||||
console.log(createContextualError('NO_MEMORIES', options.project || 'this project'));
|
||||
}
|
||||
return;
|
||||
}
|
||||
|
||||
const content = fs.readFileSync(indexPath, 'utf-8');
|
||||
const lines = content.trim().split('\n').filter(line => line.trim());
|
||||
|
||||
if (lines.length === 0) {
|
||||
if (options.format === 'session-start') {
|
||||
console.log(createContextualError('NO_MEMORIES', options.project || 'this project'));
|
||||
}
|
||||
return;
|
||||
}
|
||||
|
||||
// Parse JSONL format - each line is a JSON object
|
||||
const jsonObjects: any[] = [];
|
||||
for (const line of lines) {
|
||||
try {
|
||||
// Skip lines that don't look like JSON (could be legacy format)
|
||||
if (!line.trim().startsWith('{')) {
|
||||
continue;
|
||||
}
|
||||
const obj = JSON.parse(line);
|
||||
jsonObjects.push(obj);
|
||||
} catch (e) {
|
||||
// Skip malformed JSON lines
|
||||
continue;
|
||||
}
|
||||
}
|
||||
|
||||
if (jsonObjects.length === 0) {
|
||||
if (options.format === 'session-start') {
|
||||
console.log(createContextualError('NO_MEMORIES', options.project || 'this project'));
|
||||
}
|
||||
return;
|
||||
}
|
||||
|
||||
// Separate memories, overviews, and other types
|
||||
const memories = jsonObjects.filter(obj => obj.type === 'memory');
|
||||
const overviews = jsonObjects.filter(obj => obj.type === 'overview');
|
||||
const sessions = jsonObjects.filter(obj => obj.type === 'session');
|
||||
|
||||
// Filter each type by project if specified
|
||||
// Handle both hyphen and underscore formats since index has mixed entries
|
||||
let filteredMemories = memories;
|
||||
let filteredOverviews = overviews;
|
||||
let filteredSessions = sessions;
|
||||
if (options.project) {
|
||||
const matchesProject = buildProjectMatcher(options.project);
|
||||
filteredMemories = memories.filter(obj => matchesProject(obj.project));
|
||||
filteredOverviews = overviews.filter(obj => matchesProject(obj.project));
|
||||
filteredSessions = sessions.filter(obj => matchesProject(obj.project));
|
||||
}
|
||||
|
||||
if (options.format === 'session-start') {
|
||||
// Get last 10 memories and last 5 overviews for session-start
|
||||
const recentMemories = filteredMemories.slice(-10);
|
||||
const recentOverviews = filteredOverviews.slice(-5);
|
||||
const recentSessions = filteredSessions.slice(-5);
|
||||
|
||||
// Combine them for the display
|
||||
const recentObjects = [...recentSessions, ...recentMemories, ...recentOverviews];
|
||||
|
||||
// Find most recent timestamp for last session info
|
||||
let lastSessionTime = 'recently';
|
||||
const timestamps = recentObjects
|
||||
.map(obj => {
|
||||
// Get timestamp from JSON object
|
||||
return obj.timestamp ? new Date(obj.timestamp) : null;
|
||||
})
|
||||
.filter(date => date !== null)
|
||||
.sort((a, b) => b.getTime() - a.getTime());
|
||||
|
||||
if (timestamps.length > 0) {
|
||||
lastSessionTime = formatTimeAgo(timestamps[0]);
|
||||
}
|
||||
|
||||
// Use dual-stream output for session start formatting
|
||||
outputSessionStartContent({
|
||||
projectName: options.project || 'your project',
|
||||
memoryCount: recentMemories.length,
|
||||
lastSessionTime,
|
||||
recentObjects
|
||||
});
|
||||
|
||||
} else if (options.format === 'json') {
|
||||
// For JSON format, combine last 10 of each type
|
||||
const recentMemories = filteredMemories.slice(-10);
|
||||
const recentOverviews = filteredOverviews.slice(-3);
|
||||
const recentObjects = [...recentMemories, ...recentOverviews];
|
||||
console.log(JSON.stringify(recentObjects));
|
||||
} else {
|
||||
// Default format - show last 10 memories and last 3 overviews
|
||||
const recentMemories = filteredMemories.slice(-10);
|
||||
const recentOverviews = filteredOverviews.slice(-3);
|
||||
const totalCount = recentMemories.length + recentOverviews.length;
|
||||
|
||||
console.log(createCompletionMessage('Context loading', totalCount, 'recent entries found'));
|
||||
|
||||
// Show memories first
|
||||
recentMemories.forEach((obj) => {
|
||||
console.log(`${obj.text} | ${obj.document_id} | ${obj.keywords}`);
|
||||
});
|
||||
|
||||
// Then show overviews
|
||||
recentOverviews.forEach((obj) => {
|
||||
console.log(`**Overview:** ${obj.content}`);
|
||||
});
|
||||
}
|
||||
|
||||
// Display trash status if not empty (except for JSON format to avoid breaking JSON parsing)
|
||||
if (options.format !== 'json') {
|
||||
const trashStatus = getTrashStatus();
|
||||
if (!trashStatus.isEmpty) {
|
||||
const formattedSize = formatSize(trashStatus.totalSize);
|
||||
console.log(`🗑️ Trash – ${trashStatus.folderCount} folders | ${trashStatus.fileCount} files | ${formattedSize} – use \`$ claude-mem restore\``);
|
||||
console.log('');
|
||||
}
|
||||
}
|
||||
|
||||
} catch (error) {
|
||||
const errorMessage = error instanceof Error ? error.message : String(error);
|
||||
if (options.format === 'session-start') {
|
||||
console.log(createContextualError('CONNECTION_FAILED', errorMessage));
|
||||
} else {
|
||||
console.log(createUserFriendlyError('Context loading', errorMessage, 'Check file permissions and try again'));
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,84 @@
|
||||
import { OptionValues } from 'commander';
|
||||
import { readFileSync, readdirSync, statSync } from 'fs';
|
||||
import { join } from 'path';
|
||||
import { PathDiscovery } from '../services/path-discovery.js';
|
||||
|
||||
// <Block> 1.1 ====================================
|
||||
async function showLog(logPath: string, logType: string, tail: number): Promise<void> {
|
||||
// <Block> 1.2 ====================================
|
||||
try {
|
||||
const content = readFileSync(logPath, 'utf8');
|
||||
const lines = content.split('\n').filter(line => line.trim());
|
||||
const displayLines = lines.slice(-tail);
|
||||
|
||||
console.log(`📋 ${logType} Logs (last ${tail} lines):`);
|
||||
console.log(` File: ${logPath}`);
|
||||
console.log('');
|
||||
|
||||
// <Block> 1.3 ====================================
|
||||
if (displayLines.length === 0) {
|
||||
console.log(' No log entries found');
|
||||
// </Block> =======================================
|
||||
} else {
|
||||
displayLines.forEach(line => {
|
||||
console.log(` ${line}`);
|
||||
});
|
||||
}
|
||||
// </Block> =======================================
|
||||
|
||||
console.log('');
|
||||
// </Block> =======================================
|
||||
} catch (error) {
|
||||
// <Block> 1.4 ====================================
|
||||
console.log(`❌ Could not read ${logType.toLowerCase()} log: ${logPath}`);
|
||||
// </Block> =======================================
|
||||
}
|
||||
// </Block> =======================================
|
||||
}
|
||||
|
||||
// <Block> 2.1 ====================================
|
||||
export async function logs(options: OptionValues = {}): Promise<void> {
|
||||
// <Block> 2.2 ====================================
|
||||
const logsDir = PathDiscovery.getLogsDirectory();
|
||||
const tail = parseInt(options.tail) || 20;
|
||||
// </Block> =======================================
|
||||
|
||||
// Find most recent log file
|
||||
try {
|
||||
const files = readdirSync(logsDir);
|
||||
const logFiles = files
|
||||
.filter(f => f.startsWith('claude-mem-') && f.endsWith('.log'))
|
||||
.map(f => ({
|
||||
name: f,
|
||||
path: join(logsDir, f),
|
||||
mtime: statSync(join(logsDir, f)).mtime
|
||||
}))
|
||||
.sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
|
||||
|
||||
if (logFiles.length === 0) {
|
||||
console.log('❌ No log files found in ~/.claude-mem/logs/');
|
||||
return;
|
||||
}
|
||||
|
||||
// Show most recent log
|
||||
await showLog(logFiles[0].path, 'Most Recent', tail);
|
||||
|
||||
if (options.all && logFiles.length > 1) {
|
||||
console.log(`📚 Found ${logFiles.length} total log files`);
|
||||
}
|
||||
} catch (error) {
|
||||
console.log('❌ Could not read logs directory: ~/.claude-mem/logs/');
|
||||
console.log(' Run a compression first to generate logs');
|
||||
}
|
||||
|
||||
// <Block> 2.5 ====================================
|
||||
if (options.follow) {
|
||||
console.log('Following logs... (Press Ctrl+C to stop)');
|
||||
// Basic follow implementation - would need more sophisticated watching in real usage
|
||||
setInterval(() => {
|
||||
// This would need proper file watching implementation
|
||||
}, 1000);
|
||||
}
|
||||
// </Block> =======================================
|
||||
// </Block> =======================================
|
||||
}
|
||||
@@ -0,0 +1,24 @@
|
||||
import { readdirSync, renameSync } from 'fs';
|
||||
import { join } from 'path';
|
||||
import * as p from '@clack/prompts';
|
||||
import { PathDiscovery } from '../services/path-discovery.js';
|
||||
|
||||
export async function restore(): Promise<void> {
|
||||
const trashDir = PathDiscovery.getInstance().getTrashDirectory();
|
||||
const files = readdirSync(trashDir);
|
||||
|
||||
if (files.length === 0) {
|
||||
console.log('Trash is empty');
|
||||
return;
|
||||
}
|
||||
|
||||
const file = await p.select({
|
||||
message: 'Select file to restore:',
|
||||
options: files.map(f => ({ value: f, label: f }))
|
||||
});
|
||||
|
||||
if (p.isCancel(file)) return;
|
||||
|
||||
renameSync(join(trashDir, file), join(process.cwd(), file));
|
||||
console.log(`Restored ${file}`);
|
||||
}
|
||||
@@ -0,0 +1,75 @@
|
||||
import { OptionValues } from 'commander';
|
||||
import { appendFileSync } from 'fs';
|
||||
import { PathDiscovery } from '../services/path-discovery.js';
|
||||
|
||||
/**
|
||||
* Generates a descriptive session ID from the message content
|
||||
* Takes first few meaningful words and creates a readable identifier
|
||||
*/
|
||||
function generateSessionId(message: string): string {
|
||||
// Remove punctuation and split into words
|
||||
const words = message
|
||||
.toLowerCase()
|
||||
.replace(/[^\w\s]/g, ' ')
|
||||
.split(/\s+/)
|
||||
.filter(word => word.length > 2); // Skip short words like 'a', 'is', 'to'
|
||||
|
||||
// Take first 3-4 meaningful words, max 30 chars
|
||||
const sessionWords = words.slice(0, 4).join('-');
|
||||
const truncated = sessionWords.length > 30 ? sessionWords.substring(0, 27) + '...' : sessionWords;
|
||||
|
||||
// Add timestamp suffix to ensure uniqueness
|
||||
const timestamp = new Date().toISOString().substring(11, 19).replace(/:/g, '');
|
||||
|
||||
return `${truncated}-${timestamp}`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Save command - stores a message to both Chroma collection and JSONL index
|
||||
*/
|
||||
export async function save(message: string, options: OptionValues = {}): Promise<void> {
|
||||
// Debug: Log what we receive
|
||||
appendFileSync('/Users/alexnewman/.claude-mem/save-debug.log',
|
||||
`[${new Date().toISOString()}] Received message: "${message}" (type: ${typeof message}, length: ${message?.length})\n`,
|
||||
'utf8');
|
||||
|
||||
if (!message || message.trim() === '') {
|
||||
console.error('Error: Message is required');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const pathDiscovery = PathDiscovery.getInstance();
|
||||
const timestamp = new Date().toISOString();
|
||||
const projectName = PathDiscovery.getCurrentProjectName();
|
||||
const sessionId = generateSessionId(message);
|
||||
const documentId = `${projectName}_${sessionId}_overview`;
|
||||
|
||||
// 1. Save to Chroma collection (skip for now - MCP tools only available in Claude Code context)
|
||||
// TODO: Add Chroma integration when called from Claude Code with MCP server running
|
||||
|
||||
// 2. Append to JSONL index file
|
||||
const indexPath = pathDiscovery.getIndexPath();
|
||||
const indexEntry = {
|
||||
type: "overview",
|
||||
content: message,
|
||||
session_id: sessionId,
|
||||
project: projectName,
|
||||
timestamp: timestamp
|
||||
};
|
||||
|
||||
// Ensure the directory exists
|
||||
pathDiscovery.ensureDirectory(pathDiscovery.getDataDirectory());
|
||||
|
||||
// Append to JSONL file
|
||||
appendFileSync(indexPath, JSON.stringify(indexEntry) + '\n', 'utf8');
|
||||
|
||||
// 3. Return JSON response for hook compatibility
|
||||
console.log(JSON.stringify({
|
||||
success: true,
|
||||
document_id: documentId,
|
||||
session_id: sessionId,
|
||||
project: projectName,
|
||||
timestamp: timestamp,
|
||||
suppressOutput: true
|
||||
}));
|
||||
}
|
||||
@@ -0,0 +1,176 @@
|
||||
import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
|
||||
import { join, resolve, dirname } from 'path';
|
||||
import { execSync } from 'child_process';
|
||||
import { fileURLToPath } from 'url';
|
||||
import { PathDiscovery } from '../services/path-discovery.js';
|
||||
|
||||
const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||
|
||||
export async function status(): Promise<void> {
|
||||
console.log('🔍 Claude Memory System Status Check');
|
||||
console.log('=====================================\n');
|
||||
|
||||
console.log('📂 Installed Hook Scripts:');
|
||||
const pathDiscovery = PathDiscovery.getInstance();
|
||||
const claudeMemHooksDir = pathDiscovery.getHooksDirectory();
|
||||
const preCompactScript = join(claudeMemHooksDir, 'pre-compact.js');
|
||||
const sessionStartScript = join(claudeMemHooksDir, 'session-start.js');
|
||||
const sessionEndScript = join(claudeMemHooksDir, 'session-end.js');
|
||||
|
||||
const checkScript = (path: string, name: string) => {
|
||||
if (existsSync(path)) {
|
||||
console.log(` ✅ ${name}: Found at ${path}`);
|
||||
} else {
|
||||
console.log(` ❌ ${name}: Not found at ${path}`);
|
||||
}
|
||||
};
|
||||
|
||||
checkScript(preCompactScript, 'pre-compact.js');
|
||||
checkScript(sessionStartScript, 'session-start.js');
|
||||
checkScript(sessionEndScript, 'session-end.js');
|
||||
|
||||
console.log('');
|
||||
|
||||
console.log('⚙️ Settings Configuration:');
|
||||
|
||||
const checkSettings = (name: string, path: string) => {
|
||||
if (!existsSync(path)) {
|
||||
console.log(` ⏭️ ${name}: No settings file`);
|
||||
return;
|
||||
}
|
||||
|
||||
console.log(` 📋 ${name}: ${path}`);
|
||||
|
||||
try {
|
||||
const settings = JSON.parse(readFileSync(path, 'utf8'));
|
||||
|
||||
const hasPreCompact = settings.hooks?.PreCompact?.some((matcher: any) =>
|
||||
matcher.hooks?.some((hook: any) =>
|
||||
hook.command?.includes('pre-compact.js') || hook.command?.includes('claude-mem')
|
||||
)
|
||||
);
|
||||
|
||||
const hasSessionStart = settings.hooks?.SessionStart?.some((matcher: any) =>
|
||||
matcher.hooks?.some((hook: any) =>
|
||||
hook.command?.includes('session-start.js') || hook.command?.includes('claude-mem')
|
||||
)
|
||||
);
|
||||
|
||||
const hasSessionEnd = settings.hooks?.SessionEnd?.some((matcher: any) =>
|
||||
matcher.hooks?.some((hook: any) =>
|
||||
hook.command?.includes('session-end.js') || hook.command?.includes('claude-mem')
|
||||
)
|
||||
);
|
||||
|
||||
console.log(` PreCompact: ${hasPreCompact ? '✅' : '❌'}`);
|
||||
console.log(` SessionStart: ${hasSessionStart ? '✅' : '❌'}`);
|
||||
console.log(` SessionEnd: ${hasSessionEnd ? '✅' : '❌'}`);
|
||||
|
||||
} catch (error: any) {
|
||||
console.log(` ⚠️ Could not parse settings`);
|
||||
}
|
||||
};
|
||||
|
||||
checkSettings('Global', pathDiscovery.getClaudeSettingsPath());
|
||||
checkSettings('Project', join(process.cwd(), '.claude', 'settings.json'));
|
||||
|
||||
console.log('');
|
||||
|
||||
console.log('📦 Compressed Transcripts:');
|
||||
const claudeProjectsDir = join(pathDiscovery.getClaudeConfigDirectory(), 'projects');
|
||||
|
||||
if (existsSync(claudeProjectsDir)) {
|
||||
try {
|
||||
let compressedCount = 0;
|
||||
let archiveCount = 0;
|
||||
|
||||
const searchDir = (dir: string, depth = 0) => {
|
||||
if (depth > 3) return;
|
||||
|
||||
const files = readdirSync(dir);
|
||||
for (const file of files) {
|
||||
const fullPath = join(dir, file);
|
||||
const stats = statSync(fullPath);
|
||||
|
||||
if (stats.isDirectory() && !file.startsWith('.')) {
|
||||
searchDir(fullPath, depth + 1);
|
||||
} else if (file.endsWith('.jsonl.compressed')) {
|
||||
compressedCount++;
|
||||
} else if (file.endsWith('.jsonl.archive')) {
|
||||
archiveCount++;
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
searchDir(claudeProjectsDir);
|
||||
|
||||
console.log(` Compressed files: ${compressedCount}`);
|
||||
console.log(` Archive files: ${archiveCount}`);
|
||||
|
||||
} catch (error) {
|
||||
console.log(` ⚠️ Could not scan projects directory`);
|
||||
}
|
||||
} else {
|
||||
console.log(` ℹ️ No Claude projects directory found`);
|
||||
}
|
||||
|
||||
console.log('');
|
||||
|
||||
console.log('🔧 Runtime Environment:');
|
||||
|
||||
const checkCommand = (cmd: string, name: string) => {
|
||||
try {
|
||||
const version = execSync(`${cmd} --version`, { encoding: 'utf8' }).trim();
|
||||
console.log(` ✅ ${name}: ${version}`);
|
||||
} catch {
|
||||
console.log(` ❌ ${name}: Not found`);
|
||||
}
|
||||
};
|
||||
|
||||
checkCommand('node', 'Node.js');
|
||||
checkCommand('bun', 'Bun');
|
||||
|
||||
console.log('');
|
||||
|
||||
console.log('🧠 Chroma Storage Status:');
|
||||
console.log(' ✅ Storage backend: Chroma MCP');
|
||||
console.log(` 📍 Data location: ${pathDiscovery.getChromaDirectory()}`);
|
||||
console.log(' 🔍 Features: Vector search, semantic similarity, document storage');
|
||||
|
||||
console.log('');
|
||||
|
||||
console.log('📊 Summary:');
|
||||
const globalPath = pathDiscovery.getClaudeSettingsPath();
|
||||
const projectPath = join(process.cwd(), '.claude', 'settings.json');
|
||||
|
||||
let isInstalled = false;
|
||||
let installLocation = 'Not installed';
|
||||
|
||||
try {
|
||||
if (existsSync(globalPath)) {
|
||||
const settings = JSON.parse(readFileSync(globalPath, 'utf8'));
|
||||
if (settings.hooks?.PreCompact || settings.hooks?.SessionStart || settings.hooks?.SessionEnd) {
|
||||
isInstalled = true;
|
||||
installLocation = 'Global';
|
||||
}
|
||||
}
|
||||
|
||||
if (existsSync(projectPath)) {
|
||||
const settings = JSON.parse(readFileSync(projectPath, 'utf8'));
|
||||
if (settings.hooks?.PreCompact || settings.hooks?.SessionStart || settings.hooks?.SessionEnd) {
|
||||
isInstalled = true;
|
||||
installLocation = installLocation === 'Global' ? 'Global + Project' : 'Project';
|
||||
}
|
||||
}
|
||||
} catch {}
|
||||
|
||||
if (isInstalled) {
|
||||
console.log(` ✅ Claude Memory System is installed (${installLocation})`);
|
||||
console.log('');
|
||||
console.log('💡 To test: Use /compact in Claude Code');
|
||||
} else {
|
||||
console.log(` ❌ Claude Memory System is not installed`);
|
||||
console.log('');
|
||||
console.log('💡 To install: claude-mem install');
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,66 @@
|
||||
import { rmSync, readdirSync, existsSync, statSync } from 'fs';
|
||||
import { join } from 'path';
|
||||
import * as p from '@clack/prompts';
|
||||
import { PathDiscovery } from '../services/path-discovery.js';
|
||||
|
||||
export async function emptyTrash(options: { force?: boolean } = {}): Promise<void> {
|
||||
const trashDir = PathDiscovery.getInstance().getTrashDirectory();
|
||||
|
||||
// Check if trash directory exists
|
||||
if (!existsSync(trashDir)) {
|
||||
p.log.info('🗑️ Trash is already empty');
|
||||
return;
|
||||
}
|
||||
|
||||
try {
|
||||
const files = readdirSync(trashDir);
|
||||
|
||||
if (files.length === 0) {
|
||||
p.log.info('🗑️ Trash is already empty');
|
||||
return;
|
||||
}
|
||||
|
||||
// Count items
|
||||
let folderCount = 0;
|
||||
let fileCount = 0;
|
||||
|
||||
for (const file of files) {
|
||||
const filePath = join(trashDir, file);
|
||||
const stats = statSync(filePath);
|
||||
if (stats.isDirectory()) {
|
||||
folderCount++;
|
||||
} else {
|
||||
fileCount++;
|
||||
}
|
||||
}
|
||||
|
||||
// Confirm deletion unless --force flag is used
|
||||
if (!options.force) {
|
||||
const confirm = await p.confirm({
|
||||
message: `Permanently delete ${folderCount} folders and ${fileCount} files from trash?`,
|
||||
initialValue: false
|
||||
});
|
||||
|
||||
if (p.isCancel(confirm) || !confirm) {
|
||||
p.log.info('Cancelled - trash not emptied');
|
||||
return;
|
||||
}
|
||||
}
|
||||
|
||||
// Delete all files in trash
|
||||
const s = p.spinner();
|
||||
s.start('Emptying trash...');
|
||||
|
||||
for (const file of files) {
|
||||
const filePath = join(trashDir, file);
|
||||
rmSync(filePath, { recursive: true, force: true });
|
||||
}
|
||||
|
||||
s.stop(`🗑️ Trash emptied - permanently deleted ${folderCount} folders and ${fileCount} files`);
|
||||
|
||||
} catch (error) {
|
||||
p.log.error('Failed to empty trash');
|
||||
console.error(error);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,124 @@
|
||||
import { readdirSync, statSync } from 'fs';
|
||||
import { join, basename } from 'path';
|
||||
import * as p from '@clack/prompts';
|
||||
import { PathDiscovery } from '../services/path-discovery.js';
|
||||
|
||||
interface TrashItem {
|
||||
originalName: string;
|
||||
trashedName: string;
|
||||
size: number;
|
||||
trashedAt: Date;
|
||||
isDirectory: boolean;
|
||||
}
|
||||
|
||||
function parseTrashName(filename: string): { name: string; timestamp: number } {
|
||||
const lastDotIndex = filename.lastIndexOf('.');
|
||||
if (lastDotIndex === -1) return { name: filename, timestamp: 0 };
|
||||
|
||||
const timestamp = parseInt(filename.substring(lastDotIndex + 1));
|
||||
if (isNaN(timestamp)) return { name: filename, timestamp: 0 };
|
||||
|
||||
return {
|
||||
name: filename.substring(0, lastDotIndex),
|
||||
timestamp
|
||||
};
|
||||
}
|
||||
|
||||
function formatSize(bytes: number): string {
|
||||
if (bytes === 0) return '0 B';
|
||||
const k = 1024;
|
||||
const sizes = ['B', 'KB', 'MB', 'GB'];
|
||||
const i = Math.floor(Math.log(bytes) / Math.log(k));
|
||||
return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
|
||||
}
|
||||
|
||||
function getDirectorySize(dirPath: string): number {
|
||||
let size = 0;
|
||||
const files = readdirSync(dirPath);
|
||||
|
||||
for (const file of files) {
|
||||
const filePath = join(dirPath, file);
|
||||
const stats = statSync(filePath);
|
||||
|
||||
if (stats.isDirectory()) {
|
||||
size += getDirectorySize(filePath);
|
||||
} else {
|
||||
size += stats.size;
|
||||
}
|
||||
}
|
||||
|
||||
return size;
|
||||
}
|
||||
|
||||
export async function viewTrash(): Promise<void> {
|
||||
const trashDir = PathDiscovery.getInstance().getTrashDirectory();
|
||||
|
||||
try {
|
||||
const files = readdirSync(trashDir);
|
||||
|
||||
if (files.length === 0) {
|
||||
p.log.info('🗑️ Trash is empty');
|
||||
return;
|
||||
}
|
||||
|
||||
const items: TrashItem[] = files.map(file => {
|
||||
const filePath = join(trashDir, file);
|
||||
const stats = statSync(filePath);
|
||||
const { name, timestamp } = parseTrashName(file);
|
||||
|
||||
const size = stats.isDirectory() ? getDirectorySize(filePath) : stats.size;
|
||||
|
||||
return {
|
||||
originalName: name,
|
||||
trashedName: file,
|
||||
size,
|
||||
trashedAt: new Date(timestamp),
|
||||
isDirectory: stats.isDirectory()
|
||||
};
|
||||
});
|
||||
|
||||
// Sort by date, newest first
|
||||
items.sort((a, b) => b.trashedAt.getTime() - a.trashedAt.getTime());
|
||||
|
||||
// Display header
|
||||
console.log('\n🗑️ Trash Contents\n');
|
||||
console.log('─'.repeat(80));
|
||||
|
||||
// Display items
|
||||
let totalSize = 0;
|
||||
let folderCount = 0;
|
||||
let fileCount = 0;
|
||||
|
||||
for (const item of items) {
|
||||
totalSize += item.size;
|
||||
if (item.isDirectory) {
|
||||
folderCount++;
|
||||
} else {
|
||||
fileCount++;
|
||||
}
|
||||
|
||||
const type = item.isDirectory ? '📁' : '📄';
|
||||
const date = item.trashedAt.toLocaleString();
|
||||
const size = formatSize(item.size);
|
||||
|
||||
console.log(`${type} ${item.originalName}`);
|
||||
console.log(` Size: ${size} | Trashed: ${date}`);
|
||||
console.log(` ID: ${item.trashedName}`);
|
||||
console.log();
|
||||
}
|
||||
|
||||
// Display summary
|
||||
console.log('─'.repeat(80));
|
||||
console.log(`Total: ${folderCount} folders, ${fileCount} files (${formatSize(totalSize)})`);
|
||||
console.log('\nTo restore files: claude-mem restore');
|
||||
console.log('To empty trash: claude-mem trash empty');
|
||||
|
||||
} catch (error) {
|
||||
if ((error as any).code === 'ENOENT') {
|
||||
p.log.info('🗑️ Trash is empty');
|
||||
} else {
|
||||
p.log.error('Failed to read trash directory');
|
||||
console.error(error);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,60 @@
|
||||
import { renameSync, existsSync, mkdirSync, statSync } from 'fs';
|
||||
import { join, basename } from 'path';
|
||||
import { glob } from 'glob';
|
||||
import { PathDiscovery } from '../services/path-discovery.js';
|
||||
|
||||
interface TrashOptions {
|
||||
force?: boolean;
|
||||
recursive?: boolean;
|
||||
}
|
||||
|
||||
export async function trash(filePaths: string | string[], options: TrashOptions = {}): Promise<void> {
|
||||
const trashDir = PathDiscovery.getInstance().getTrashDirectory();
|
||||
if (!existsSync(trashDir)) mkdirSync(trashDir, { recursive: true });
|
||||
|
||||
// Handle single string or array of paths
|
||||
const paths = Array.isArray(filePaths) ? filePaths : [filePaths];
|
||||
|
||||
for (const filePath of paths) {
|
||||
// Handle glob patterns
|
||||
const expandedPaths = await glob(filePath);
|
||||
const actualPaths = expandedPaths.length > 0 ? expandedPaths : [filePath];
|
||||
|
||||
for (const actualPath of actualPaths) {
|
||||
try {
|
||||
// Check if file exists
|
||||
if (!existsSync(actualPath)) {
|
||||
if (!options.force) {
|
||||
console.error(`trash: ${actualPath}: No such file or directory`);
|
||||
continue;
|
||||
}
|
||||
// With -f, silently skip missing files
|
||||
continue;
|
||||
}
|
||||
|
||||
// Check if it's a directory and we need recursive
|
||||
const stats = statSync(actualPath);
|
||||
if (stats.isDirectory() && !options.recursive) {
|
||||
if (!options.force) {
|
||||
console.error(`trash: ${actualPath}: is a directory`);
|
||||
continue;
|
||||
}
|
||||
}
|
||||
|
||||
// Generate unique destination name to avoid conflicts
|
||||
const fileName = basename(actualPath);
|
||||
const timestamp = Date.now();
|
||||
const destination = join(trashDir, `${fileName}.${timestamp}`);
|
||||
|
||||
renameSync(actualPath, destination);
|
||||
console.log(`Moved ${fileName} to trash`);
|
||||
|
||||
} catch (error) {
|
||||
if (!options.force) {
|
||||
const errorMessage = error instanceof Error ? error.message : String(error);
|
||||
console.error(`trash: ${actualPath}: ${errorMessage}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,133 @@
|
||||
import { OptionValues } from 'commander';
|
||||
import { readFileSync, writeFileSync, existsSync } from 'fs';
|
||||
import { join } from 'path';
|
||||
import { PathDiscovery } from '../services/path-discovery.js';
|
||||
|
||||
export async function uninstall(options: OptionValues = {}): Promise<void> {
|
||||
console.log('🔄 Uninstalling Claude Memory System hooks...');
|
||||
|
||||
const locations = [];
|
||||
if (options.all) {
|
||||
locations.push({
|
||||
name: 'User',
|
||||
path: PathDiscovery.getInstance().getClaudeSettingsPath()
|
||||
});
|
||||
locations.push({
|
||||
name: 'Project',
|
||||
path: join(process.cwd(), '.claude', 'settings.json')
|
||||
});
|
||||
} else {
|
||||
const isProject = options.project;
|
||||
const pathDiscovery = PathDiscovery.getInstance();
|
||||
locations.push({
|
||||
name: isProject ? 'Project' : 'User',
|
||||
path: isProject ? join(process.cwd(), '.claude', 'settings.json') : pathDiscovery.getClaudeSettingsPath()
|
||||
});
|
||||
}
|
||||
|
||||
const pathDiscovery = PathDiscovery.getInstance();
|
||||
const claudeMemHooksDir = pathDiscovery.getHooksDirectory();
|
||||
const preCompactScript = join(claudeMemHooksDir, 'pre-compact.js');
|
||||
const sessionStartScript = join(claudeMemHooksDir, 'session-start.js');
|
||||
const sessionEndScript = join(claudeMemHooksDir, 'session-end.js');
|
||||
|
||||
let removedCount = 0;
|
||||
|
||||
for (const location of locations) {
|
||||
if (!existsSync(location.path)) {
|
||||
console.log(`⏭️ No settings found at ${location.name} location`);
|
||||
continue;
|
||||
}
|
||||
|
||||
try {
|
||||
const content = readFileSync(location.path, 'utf8');
|
||||
const settings = JSON.parse(content);
|
||||
|
||||
if (!settings.hooks) {
|
||||
console.log(`⏭️ No hooks configured in ${location.name} settings`);
|
||||
continue;
|
||||
}
|
||||
|
||||
let modified = false;
|
||||
|
||||
if (settings.hooks.PreCompact) {
|
||||
const filteredPreCompact = settings.hooks.PreCompact.filter((matcher: any) =>
|
||||
!matcher.hooks?.some((hook: any) =>
|
||||
hook.command === preCompactScript ||
|
||||
hook.command?.includes('pre-compact.js') ||
|
||||
hook.command?.includes('claude-mem')
|
||||
)
|
||||
);
|
||||
|
||||
if (filteredPreCompact.length !== settings.hooks.PreCompact.length) {
|
||||
settings.hooks.PreCompact = filteredPreCompact.length ? filteredPreCompact : undefined;
|
||||
modified = true;
|
||||
console.log(`✅ Removed PreCompact hook from ${location.name} settings`);
|
||||
}
|
||||
}
|
||||
|
||||
if (settings.hooks.SessionStart) {
|
||||
const filteredSessionStart = settings.hooks.SessionStart.filter((matcher: any) =>
|
||||
!matcher.hooks?.some((hook: any) =>
|
||||
hook.command === sessionStartScript ||
|
||||
hook.command?.includes('session-start.js') ||
|
||||
hook.command?.includes('claude-mem')
|
||||
)
|
||||
);
|
||||
|
||||
if (filteredSessionStart.length !== settings.hooks.SessionStart.length) {
|
||||
settings.hooks.SessionStart = filteredSessionStart.length ? filteredSessionStart : undefined;
|
||||
modified = true;
|
||||
console.log(`✅ Removed SessionStart hook from ${location.name} settings`);
|
||||
}
|
||||
}
|
||||
|
||||
if (settings.hooks.SessionEnd) {
|
||||
const filteredSessionEnd = settings.hooks.SessionEnd.filter((matcher: any) =>
|
||||
!matcher.hooks?.some((hook: any) =>
|
||||
hook.command === sessionEndScript ||
|
||||
hook.command?.includes('session-end.js') ||
|
||||
hook.command?.includes('claude-mem')
|
||||
)
|
||||
);
|
||||
|
||||
if (filteredSessionEnd.length !== settings.hooks.SessionEnd.length) {
|
||||
settings.hooks.SessionEnd = filteredSessionEnd.length ? filteredSessionEnd : undefined;
|
||||
modified = true;
|
||||
console.log(`✅ Removed SessionEnd hook from ${location.name} settings`);
|
||||
}
|
||||
}
|
||||
|
||||
if (settings.hooks.PreCompact === undefined) delete settings.hooks.PreCompact;
|
||||
if (settings.hooks.SessionStart === undefined) delete settings.hooks.SessionStart;
|
||||
if (settings.hooks.SessionEnd === undefined) delete settings.hooks.SessionEnd;
|
||||
if (!Object.keys(settings.hooks).length) delete settings.hooks;
|
||||
|
||||
if (modified) {
|
||||
const backupPath = location.path + '.backup.' + Date.now();
|
||||
writeFileSync(backupPath, content);
|
||||
console.log(`📋 Created backup: ${backupPath}`);
|
||||
|
||||
writeFileSync(location.path, JSON.stringify(settings, null, 2));
|
||||
removedCount++;
|
||||
console.log(`✅ Updated ${location.name} settings: ${location.path}`);
|
||||
} else {
|
||||
console.log(`ℹ️ No Claude Memory System hooks found in ${location.name} settings`);
|
||||
}
|
||||
|
||||
} catch (error: any) {
|
||||
console.log(`⚠️ Could not process ${location.name} settings: ${error.message}`);
|
||||
}
|
||||
}
|
||||
|
||||
console.log('');
|
||||
if (removedCount > 0) {
|
||||
console.log('✨ Uninstallation complete!');
|
||||
console.log('The Claude Memory System hooks have been removed from your settings.');
|
||||
console.log('');
|
||||
console.log('Note: Your compressed transcripts and archives are preserved.');
|
||||
console.log('To reinstall: claude-mem install');
|
||||
} else {
|
||||
console.log('ℹ️ No Claude Memory System hooks were found to remove.');
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,206 @@
|
||||
/**
|
||||
* Claude Memory System - Core Constants
|
||||
*
|
||||
* This file contains core application constants, CLI messages,
|
||||
* configuration templates, and infrastructure-related constants.
|
||||
*/
|
||||
|
||||
// =============================================================================
|
||||
// CONFIGURATION TEMPLATES
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Hook configuration templates for Claude settings
|
||||
*/
|
||||
export const HOOK_CONFIG_TEMPLATES = {
|
||||
PRE_COMPACT: (scriptPath: string) => ({
|
||||
pattern: "*",
|
||||
hooks: [{
|
||||
type: "command",
|
||||
command: scriptPath,
|
||||
timeout: 180
|
||||
}]
|
||||
}),
|
||||
|
||||
SESSION_START: (scriptPath: string) => ({
|
||||
pattern: "*",
|
||||
hooks: [{
|
||||
type: "command",
|
||||
command: scriptPath,
|
||||
timeout: 30
|
||||
}]
|
||||
}),
|
||||
|
||||
SESSION_END: (scriptPath: string) => ({
|
||||
pattern: "*",
|
||||
hooks: [{
|
||||
type: "command",
|
||||
command: scriptPath,
|
||||
timeout: 180
|
||||
}]
|
||||
})
|
||||
} as const;
|
||||
|
||||
// =============================================================================
|
||||
// CLI MESSAGES AND STATUS TEMPLATES
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Command-line interface messages
|
||||
*/
|
||||
export const CLI_MESSAGES = {
|
||||
INSTALLATION: {
|
||||
STARTING: '🚀 Installing Claude Memory System with Chroma...',
|
||||
SUCCESS: '🎉 Installation complete! Vector database ready.',
|
||||
HOOKS_INSTALLED: '✅ Installed hooks to ~/.claude-mem/hooks/',
|
||||
MCP_CONFIGURED: (path: string) => `✅ Configured MCP memory server in ${path}`,
|
||||
EMBEDDED_READY: '🧠 Chroma initialized for persistent semantic memory',
|
||||
ALREADY_INSTALLED: '⚠️ Claude Memory hooks are already installed.',
|
||||
USE_FORCE: ' Use --force to overwrite existing installation.',
|
||||
SETTINGS_WRITTEN: (type: string, path: string) =>
|
||||
`✅ Installed hooks in ${type} settings\n Settings file: ${path}`
|
||||
},
|
||||
|
||||
NEXT_STEPS: [
|
||||
'1. Restart Claude Code to load the new hooks',
|
||||
'2. Use `/clear` and `/compact` in Claude Code to save and compress session memories',
|
||||
'3. New sessions will automatically load relevant context'
|
||||
],
|
||||
|
||||
ERRORS: {
|
||||
HOOKS_NOT_FOUND: '❌ Hook source files not found',
|
||||
SETTINGS_WRITE_FAILED: (path: string, error: string) =>
|
||||
`❌ Failed to write settings file: ${error}\n Path: ${path}`,
|
||||
MCP_CONFIG_PARSE_FAILED: (error: string) =>
|
||||
`⚠️ Warning: Could not parse existing MCP config: ${error}`,
|
||||
MCP_CONFIG_WRITE_FAILED: (error: string) =>
|
||||
`⚠️ Warning: Could not write MCP config: ${error}`,
|
||||
COMPRESSION_FAILED: (error: string) => `❌ Compression failed: ${error}`,
|
||||
CONTEXT_LOAD_FAILED: (error: string) => `❌ Failed to load context: ${error}`
|
||||
},
|
||||
|
||||
STATUS: {
|
||||
NO_INDEX: '📚 No memory index found. Starting fresh session.',
|
||||
RECENT_MEMORIES: '🧠 Recent memories from previous sessions:',
|
||||
MEMORY_COUNT: (count: number) => `📚 Showing ${count} most recent memories`,
|
||||
FULL_CONTEXT_AVAILABLE: '💡 Full context available via MCP memory tools'
|
||||
}
|
||||
} as const;
|
||||
|
||||
// =============================================================================
|
||||
// DEBUG AND LOGGING TEMPLATES
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Debug logging message templates
|
||||
*/
|
||||
export const DEBUG_MESSAGES = {
|
||||
COMPRESSION_STARTED: '🚀 COMPRESSION STARTED',
|
||||
TRANSCRIPT_PATH: (path: string) => `📁 Transcript Path: ${path}`,
|
||||
SESSION_ID: (id: string) => `🔍 Session ID: ${id}`,
|
||||
PROJECT_NAME: (name: string) => `📝 PROJECT NAME: ${name}`,
|
||||
CLAUDE_SDK_CALL: '🤖 Calling Claude SDK to analyze and populate memory database...',
|
||||
TRANSCRIPT_STATS: (size: number, count: number) =>
|
||||
`📊 Transcript size: ${size} characters, ${count} messages`,
|
||||
COMPRESSION_COMPLETE: (count: number) => `✅ COMPRESSION COMPLETE\n Total summaries extracted: ${count}`,
|
||||
CLAUDE_PATH_FOUND: (path: string) => `🎯 Found Claude Code at: ${path}`,
|
||||
MCP_CONFIG_USED: (path: string) => `📋 Using MCP config: ${path}`
|
||||
} as const;
|
||||
|
||||
// =============================================================================
|
||||
// SEARCH AND QUERY TEMPLATES
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Memory database search templates
|
||||
*/
|
||||
export const SEARCH_TEMPLATES = {
|
||||
SEARCH_SCRIPT: (query: string) => `
|
||||
import { query } from "@anthropic-ai/claude-code";
|
||||
|
||||
const searchQuery = process.env.SEARCH_QUERY || '';
|
||||
|
||||
const result = await query({
|
||||
prompt: "Search for: " + searchQuery,
|
||||
options: {
|
||||
mcpConfig: "~/.claude/.mcp.json",
|
||||
allowedTools: ["mcp__claude-mem__chroma_query_documents"],
|
||||
outputFormat: "json"
|
||||
}
|
||||
});
|
||||
`,
|
||||
|
||||
SEARCH_PREFIX: "Search for: "
|
||||
} as const;
|
||||
|
||||
// =============================================================================
|
||||
// CHROMA INTEGRATION CONSTANTS
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Chroma collection names for documents
|
||||
*/
|
||||
export const CHROMA_COLLECTIONS = {
|
||||
DOCUMENTS: 'claude_mem_documents',
|
||||
MEMORIES: 'claude_mem_memories'
|
||||
} as const;
|
||||
|
||||
/**
|
||||
* Default Chroma configuration values
|
||||
*/
|
||||
export const CHROMA_DEFAULTS = {
|
||||
HOST: 'localhost:8000',
|
||||
COLLECTION: 'claude_mem_documents'
|
||||
} as const;
|
||||
|
||||
/**
|
||||
* Chroma-specific CLI messages
|
||||
*/
|
||||
export const CHROMA_MESSAGES = {
|
||||
CONNECTION: {
|
||||
CONNECTING: '🔗 Connecting to Chroma server...',
|
||||
CONNECTED: '✅ Connected to Chroma successfully',
|
||||
FAILED: (error: string) => `❌ Failed to connect to Chroma: ${error}`,
|
||||
DISCONNECTED: '👋 Disconnected from Chroma'
|
||||
},
|
||||
|
||||
SEARCH: {
|
||||
SEMANTIC_SEARCH: '🧠 Using semantic search with Chroma...',
|
||||
KEYWORD_SEARCH: '🔍 Using keyword search with Chroma...',
|
||||
HYBRID_SEARCH: '🔬 Using hybrid search with Chroma...',
|
||||
RESULTS_FOUND: (count: number) => `📊 Found ${count} results in Chroma`
|
||||
},
|
||||
|
||||
SETUP: {
|
||||
STARTING_CHROMA: '🚀 Starting Chroma instance...',
|
||||
CHROMA_READY: '✅ Chroma is ready and accepting connections',
|
||||
INITIALIZING_COLLECTIONS: '📋 Initializing document collections...'
|
||||
}
|
||||
} as const;
|
||||
|
||||
/**
|
||||
* Chroma error messages
|
||||
*/
|
||||
export const CHROMA_ERRORS = {
|
||||
CONNECTION_FAILED: 'Could not establish connection to Chroma server',
|
||||
MCP_SERVER_NOT_FOUND: 'Chroma MCP server not found',
|
||||
INVALID_COLLECTION: (collection: string) => `Invalid Chroma collection: ${collection}`,
|
||||
QUERY_FAILED: (query: string, error: string) => `Query failed for '${query}': ${error}`,
|
||||
DOCUMENT_CREATION_FAILED: (id: string) => `Failed to create document '${id}' in Chroma`,
|
||||
COLLECTION_CREATION_FAILED: (name: string) => `Failed to create collection '${name}' in Chroma`
|
||||
} as const;
|
||||
|
||||
/**
|
||||
* Export all core constants for easy importing
|
||||
*/
|
||||
export const CONSTANTS = {
|
||||
HOOK_CONFIG_TEMPLATES,
|
||||
CLI_MESSAGES,
|
||||
DEBUG_MESSAGES,
|
||||
SEARCH_TEMPLATES,
|
||||
// Chroma constants
|
||||
CHROMA_COLLECTIONS,
|
||||
CHROMA_DEFAULTS,
|
||||
CHROMA_MESSAGES,
|
||||
CHROMA_ERRORS
|
||||
} as const;
|
||||
@@ -0,0 +1,238 @@
|
||||
/**
|
||||
* ChunkManager - Handles intelligent chunking of large transcripts
|
||||
*
|
||||
* This class manages the splitting of large filtered transcripts into chunks
|
||||
* that fit within Claude's 32k token limit while preserving conversation context
|
||||
* and maintaining message integrity.
|
||||
*/
|
||||
|
||||
export interface ChunkMetadata {
|
||||
chunkNumber: number;
|
||||
totalChunks: number;
|
||||
startIndex: number;
|
||||
endIndex: number;
|
||||
messageCount: number;
|
||||
estimatedTokens: number;
|
||||
sizeBytes: number;
|
||||
hasOverlap: boolean;
|
||||
overlapMessages?: number;
|
||||
firstTimestamp?: string;
|
||||
lastTimestamp?: string;
|
||||
}
|
||||
|
||||
export interface ChunkingOptions {
|
||||
maxTokensPerChunk?: number; // default: 28000 (leaving 4k buffer)
|
||||
maxBytesPerChunk?: number; // default: 98000 (98KB)
|
||||
preserveContext?: boolean; // keep context overlap between chunks
|
||||
contextOverlap?: number; // messages to repeat (default: 2)
|
||||
parallel?: boolean; // process chunks in parallel
|
||||
}
|
||||
|
||||
export interface ChunkedMessage {
|
||||
content: string;
|
||||
estimatedTokens: number;
|
||||
}
|
||||
|
||||
export class ChunkManager {
|
||||
private static readonly DEFAULT_MAX_TOKENS = 22400; // Reduced by 20% from 28000
|
||||
private static readonly DEFAULT_MAX_BYTES = 78400; // Reduced by 20% from 98000
|
||||
private static readonly DEFAULT_CONTEXT_OVERLAP = 2;
|
||||
private static readonly CHARS_PER_TOKEN_ESTIMATE = 3.5;
|
||||
|
||||
private options: Required<ChunkingOptions>;
|
||||
|
||||
constructor(options: ChunkingOptions = {}) {
|
||||
this.options = {
|
||||
maxTokensPerChunk: options.maxTokensPerChunk ?? ChunkManager.DEFAULT_MAX_TOKENS,
|
||||
maxBytesPerChunk: options.maxBytesPerChunk ?? ChunkManager.DEFAULT_MAX_BYTES,
|
||||
preserveContext: options.preserveContext ?? true,
|
||||
contextOverlap: options.contextOverlap ?? ChunkManager.DEFAULT_CONTEXT_OVERLAP,
|
||||
parallel: options.parallel ?? false
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Estimates token count for a given text
|
||||
* Uses rough approximation of 3.5 characters per token
|
||||
*/
|
||||
public estimateTokenCount(text: string): number {
|
||||
return Math.ceil(text.length / ChunkManager.CHARS_PER_TOKEN_ESTIMATE);
|
||||
}
|
||||
|
||||
/**
|
||||
* Parses the filtered output format into structured messages
|
||||
* Format: "- content"
|
||||
*/
|
||||
public parseFilteredOutput(filteredContent: string): ChunkedMessage[] {
|
||||
const lines = filteredContent.split('\n').filter(line => line.trim());
|
||||
const messages: ChunkedMessage[] = [];
|
||||
|
||||
for (const line of lines) {
|
||||
// Parse format: "- content"
|
||||
if (line.startsWith('- ')) {
|
||||
const content = line.substring(2); // Remove "- " prefix
|
||||
messages.push({
|
||||
content,
|
||||
estimatedTokens: this.estimateTokenCount(content)
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
return messages;
|
||||
}
|
||||
|
||||
/**
|
||||
* Chunks the filtered transcript into manageable pieces
|
||||
*/
|
||||
public chunkTranscript(filteredContent: string): Array<{ content: string; metadata: ChunkMetadata }> {
|
||||
const messages = this.parseFilteredOutput(filteredContent);
|
||||
const chunks: Array<{ content: string; metadata: ChunkMetadata }> = [];
|
||||
|
||||
let currentChunk: ChunkedMessage[] = [];
|
||||
let currentTokens = 0;
|
||||
let currentBytes = 0;
|
||||
let chunkStartIndex = 0;
|
||||
|
||||
for (let i = 0; i < messages.length; i++) {
|
||||
const message = messages[i];
|
||||
const messageText = this.formatMessage(message);
|
||||
const messageBytes = Buffer.byteLength(messageText, 'utf8');
|
||||
const messageTokens = message.estimatedTokens;
|
||||
|
||||
// Check if adding this message would exceed limits
|
||||
if (currentChunk.length > 0 &&
|
||||
(currentTokens + messageTokens > this.options.maxTokensPerChunk ||
|
||||
currentBytes + messageBytes > this.options.maxBytesPerChunk)) {
|
||||
|
||||
// Save current chunk
|
||||
const chunkContent = this.formatChunk(currentChunk);
|
||||
chunks.push({
|
||||
content: chunkContent,
|
||||
metadata: {
|
||||
chunkNumber: chunks.length + 1,
|
||||
totalChunks: 0, // Will be updated after all chunks are created
|
||||
startIndex: chunkStartIndex,
|
||||
endIndex: i - 1,
|
||||
messageCount: currentChunk.length,
|
||||
estimatedTokens: currentTokens,
|
||||
sizeBytes: currentBytes,
|
||||
hasOverlap: false
|
||||
}
|
||||
});
|
||||
|
||||
// Start new chunk with optional context overlap
|
||||
currentChunk = [];
|
||||
currentTokens = 0;
|
||||
currentBytes = 0;
|
||||
chunkStartIndex = i;
|
||||
|
||||
// Add overlap messages from previous chunk if enabled
|
||||
if (this.options.preserveContext && chunks.length > 0) {
|
||||
const overlapStart = Math.max(0, i - this.options.contextOverlap);
|
||||
for (let j = overlapStart; j < i; j++) {
|
||||
const overlapMessage = messages[j];
|
||||
const overlapText = this.formatMessage(overlapMessage);
|
||||
currentChunk.push(overlapMessage);
|
||||
currentTokens += overlapMessage.estimatedTokens;
|
||||
currentBytes += Buffer.byteLength(overlapText, 'utf8');
|
||||
}
|
||||
|
||||
if (currentChunk.length > 0) {
|
||||
// Mark that this chunk has overlap
|
||||
chunkStartIndex = overlapStart;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Add message to current chunk
|
||||
currentChunk.push(message);
|
||||
currentTokens += messageTokens;
|
||||
currentBytes += messageBytes;
|
||||
}
|
||||
|
||||
// Save final chunk if it has content
|
||||
if (currentChunk.length > 0) {
|
||||
const chunkContent = this.formatChunk(currentChunk);
|
||||
chunks.push({
|
||||
content: chunkContent,
|
||||
metadata: {
|
||||
chunkNumber: chunks.length + 1,
|
||||
totalChunks: 0,
|
||||
startIndex: chunkStartIndex,
|
||||
endIndex: messages.length - 1,
|
||||
messageCount: currentChunk.length,
|
||||
estimatedTokens: currentTokens,
|
||||
sizeBytes: currentBytes,
|
||||
hasOverlap: this.options.preserveContext && chunks.length > 0
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
// Update total chunks count in metadata
|
||||
chunks.forEach(chunk => {
|
||||
chunk.metadata.totalChunks = chunks.length;
|
||||
});
|
||||
|
||||
return chunks;
|
||||
}
|
||||
|
||||
/**
|
||||
* Formats a single message back to the filtered output format
|
||||
*/
|
||||
private formatMessage(message: ChunkedMessage): string {
|
||||
return `- ${message.content}`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Formats a chunk of messages
|
||||
*/
|
||||
private formatChunk(messages: ChunkedMessage[]): string {
|
||||
return messages.map(m => this.formatMessage(m)).join('\n');
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates a header for a chunk file with metadata
|
||||
*/
|
||||
public createChunkHeader(metadata: ChunkMetadata): string {
|
||||
const lines = [];
|
||||
|
||||
// Add timestamp range if available, otherwise chunk number
|
||||
if (metadata.firstTimestamp && metadata.lastTimestamp) {
|
||||
lines.push(`# ${metadata.firstTimestamp} to ${metadata.lastTimestamp} (chunk ${metadata.chunkNumber}/${metadata.totalChunks})`);
|
||||
} else {
|
||||
lines.push(`# Chunk ${metadata.chunkNumber} of ${metadata.totalChunks}`);
|
||||
}
|
||||
|
||||
return lines.join('\n') + '\n';
|
||||
}
|
||||
|
||||
/**
|
||||
* Checks if content needs chunking based on size
|
||||
*/
|
||||
public needsChunking(content: string): boolean {
|
||||
const estimatedTokens = this.estimateTokenCount(content);
|
||||
const sizeBytes = Buffer.byteLength(content, 'utf8');
|
||||
|
||||
return estimatedTokens > this.options.maxTokensPerChunk ||
|
||||
sizeBytes > this.options.maxBytesPerChunk;
|
||||
}
|
||||
|
||||
/**
|
||||
* Gets chunking statistics for logging
|
||||
*/
|
||||
public getChunkingStats(chunks: Array<{ metadata: ChunkMetadata }>): string {
|
||||
const totalMessages = chunks.reduce((sum, c) => sum + c.metadata.messageCount, 0);
|
||||
const totalTokens = chunks.reduce((sum, c) => sum + c.metadata.estimatedTokens, 0);
|
||||
const totalBytes = chunks.reduce((sum, c) => sum + c.metadata.sizeBytes, 0);
|
||||
|
||||
return [
|
||||
`📊 Chunking Statistics:`,
|
||||
` • Total chunks: ${chunks.length}`,
|
||||
` • Total messages: ${totalMessages}`,
|
||||
` • Total estimated tokens: ${totalTokens.toLocaleString()}`,
|
||||
` • Total size: ${(totalBytes / 1024).toFixed(1)} KB`,
|
||||
` • Average tokens per chunk: ${Math.round(totalTokens / chunks.length).toLocaleString()}`,
|
||||
` • Average size per chunk: ${(totalBytes / chunks.length / 1024).toFixed(1)} KB`
|
||||
].join('\n');
|
||||
}
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,366 @@
|
||||
/**
|
||||
* PromptOrchestrator - Single source of truth for all prompt generation
|
||||
*
|
||||
* This class serves as the central orchestrator for generating different types of prompts
|
||||
* used throughout the claude-mem system. It provides clear, well-typed interfaces and
|
||||
* methods for creating prompts for LLM analysis, human context, and system integration.
|
||||
*/
|
||||
|
||||
import { createAnalysisPrompt } from '../../prompts/templates/analysis/AnalysisTemplates.js';
|
||||
|
||||
// =============================================================================
|
||||
// CORE INTERFACES
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Context data for LLM analysis prompts
|
||||
*/
|
||||
export interface AnalysisContext {
|
||||
/** The transcript content to analyze */
|
||||
transcriptContent: string;
|
||||
/** Session identifier */
|
||||
sessionId: string;
|
||||
/** Project name for context */
|
||||
projectName?: string;
|
||||
/** Custom analysis instructions */
|
||||
customInstructions?: string;
|
||||
/** Compression trigger type */
|
||||
trigger?: 'manual' | 'auto';
|
||||
/** Original token count */
|
||||
originalTokens?: number;
|
||||
/** Target compression ratio */
|
||||
targetCompressionRatio?: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Context data for human-facing session prompts
|
||||
*/
|
||||
export interface SessionContext {
|
||||
/** Session identifier */
|
||||
sessionId: string;
|
||||
/** Source of the session start */
|
||||
source: 'startup' | 'compact' | 'vscode' | 'web';
|
||||
/** Project name */
|
||||
projectName?: string;
|
||||
/** Additional context to provide to the human */
|
||||
additionalContext?: string;
|
||||
/** Path to the transcript file */
|
||||
transcriptPath?: string;
|
||||
/** Working directory */
|
||||
cwd?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Context data for hook response generation
|
||||
*/
|
||||
export interface HookContext {
|
||||
/** The hook event name */
|
||||
hookEventName: string;
|
||||
/** Session identifier */
|
||||
sessionId: string;
|
||||
/** Success status */
|
||||
success: boolean;
|
||||
/** Optional message */
|
||||
message?: string;
|
||||
/** Additional data specific to the hook */
|
||||
data?: Record<string, unknown>;
|
||||
/** Whether to continue processing */
|
||||
shouldContinue?: boolean;
|
||||
/** Reason for stopping if applicable */
|
||||
stopReason?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Generated analysis prompt for LLM consumption
|
||||
*/
|
||||
export interface AnalysisPrompt {
|
||||
/** The formatted prompt text */
|
||||
prompt: string;
|
||||
/** Context used to generate the prompt */
|
||||
context: AnalysisContext;
|
||||
/** Prompt type identifier */
|
||||
type: 'analysis';
|
||||
/** Generated timestamp */
|
||||
timestamp: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Generated session prompt for human context
|
||||
*/
|
||||
export interface SessionPrompt {
|
||||
/** The formatted message text */
|
||||
message: string;
|
||||
/** Context used to generate the prompt */
|
||||
context: SessionContext;
|
||||
/** Prompt type identifier */
|
||||
type: 'session';
|
||||
/** Generated timestamp */
|
||||
timestamp: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Generated hook response
|
||||
*/
|
||||
export interface HookResponse {
|
||||
/** Whether to continue processing */
|
||||
continue: boolean;
|
||||
/** Reason for stopping if continue is false */
|
||||
stopReason?: string;
|
||||
/** Whether to suppress output */
|
||||
suppressOutput?: boolean;
|
||||
/** Hook-specific output data */
|
||||
hookSpecificOutput?: Record<string, unknown>;
|
||||
/** Context used to generate the response */
|
||||
context: HookContext;
|
||||
/** Response type identifier */
|
||||
type: 'hook';
|
||||
/** Generated timestamp */
|
||||
timestamp: string;
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// PROMPT ORCHESTRATOR CLASS
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Central orchestrator for all prompt generation in the claude-mem system
|
||||
*/
|
||||
export class PromptOrchestrator {
|
||||
private projectName: string;
|
||||
|
||||
constructor(projectName = 'claude-mem') {
|
||||
this.projectName = projectName;
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates an analysis prompt for LLM processing of transcript content
|
||||
*/
|
||||
public createAnalysisPrompt(context: AnalysisContext): AnalysisPrompt {
|
||||
const timestamp = new Date().toISOString();
|
||||
|
||||
const prompt = this.buildAnalysisPrompt(context);
|
||||
|
||||
return {
|
||||
prompt,
|
||||
context,
|
||||
type: 'analysis',
|
||||
timestamp,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates a session start prompt for human context
|
||||
*/
|
||||
public createSessionStartPrompt(context: SessionContext): SessionPrompt {
|
||||
const timestamp = new Date().toISOString();
|
||||
|
||||
const message = this.buildSessionStartMessage(context);
|
||||
|
||||
return {
|
||||
message,
|
||||
context,
|
||||
type: 'session',
|
||||
timestamp,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates a hook response for system integration
|
||||
*/
|
||||
public createHookResponse(context: HookContext): HookResponse {
|
||||
const timestamp = new Date().toISOString();
|
||||
|
||||
const response = this.buildHookResponse(context);
|
||||
|
||||
return {
|
||||
...response,
|
||||
context,
|
||||
type: 'hook',
|
||||
timestamp,
|
||||
};
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// PRIVATE PROMPT BUILDERS
|
||||
// =============================================================================
|
||||
|
||||
private buildAnalysisPrompt(context: AnalysisContext): string {
|
||||
const {
|
||||
transcriptContent,
|
||||
sessionId,
|
||||
projectName = this.projectName,
|
||||
} = context;
|
||||
|
||||
// Use project name as-is for consistency with directory names
|
||||
const projectPrefix = projectName;
|
||||
|
||||
// Use the simple prompt with the transcript included
|
||||
return createAnalysisPrompt(
|
||||
transcriptContent,
|
||||
sessionId,
|
||||
projectPrefix
|
||||
);
|
||||
}
|
||||
|
||||
private buildSessionStartMessage(context: SessionContext): string {
|
||||
const {
|
||||
sessionId,
|
||||
source,
|
||||
projectName = this.projectName,
|
||||
additionalContext,
|
||||
transcriptPath,
|
||||
cwd,
|
||||
} = context;
|
||||
|
||||
let message = `## Session Started (${source})
|
||||
|
||||
**Project**: ${projectName}
|
||||
**Session ID**: ${sessionId} `;
|
||||
|
||||
if (transcriptPath) {
|
||||
message += `**Transcript**: ${transcriptPath} `;
|
||||
}
|
||||
|
||||
if (cwd) {
|
||||
message += `**Working Directory**: ${cwd} `;
|
||||
}
|
||||
|
||||
if (additionalContext) {
|
||||
message += `\n### Additional Context\n${additionalContext}`;
|
||||
}
|
||||
|
||||
message += `\n\nMemory system is active and ready to preserve context across sessions.`;
|
||||
|
||||
return message;
|
||||
}
|
||||
|
||||
private buildHookResponse(context: HookContext): Omit<HookResponse, 'context' | 'type' | 'timestamp'> {
|
||||
const {
|
||||
hookEventName,
|
||||
success,
|
||||
message,
|
||||
data,
|
||||
shouldContinue = success,
|
||||
stopReason,
|
||||
} = context;
|
||||
|
||||
const response: Omit<HookResponse, 'context' | 'type' | 'timestamp'> = {
|
||||
continue: shouldContinue,
|
||||
suppressOutput: false,
|
||||
};
|
||||
|
||||
if (!shouldContinue && stopReason) {
|
||||
response.stopReason = stopReason;
|
||||
}
|
||||
|
||||
// Add hook-specific output based on event type
|
||||
if (hookEventName === 'SessionStart') {
|
||||
response.hookSpecificOutput = {
|
||||
hookEventName: 'SessionStart',
|
||||
additionalContext: message,
|
||||
...data,
|
||||
};
|
||||
} else if (data) {
|
||||
response.hookSpecificOutput = data;
|
||||
}
|
||||
|
||||
return response;
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// UTILITY METHODS
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Validates that an AnalysisContext has required fields
|
||||
*/
|
||||
public validateAnalysisContext(context: Partial<AnalysisContext>): context is AnalysisContext {
|
||||
return !!(context.transcriptContent && context.sessionId);
|
||||
}
|
||||
|
||||
/**
|
||||
* Validates that a SessionContext has required fields
|
||||
*/
|
||||
public validateSessionContext(context: Partial<SessionContext>): context is SessionContext {
|
||||
return !!(context.sessionId && context.source);
|
||||
}
|
||||
|
||||
/**
|
||||
* Validates that a HookContext has required fields
|
||||
*/
|
||||
public validateHookContext(context: Partial<HookContext>): context is HookContext {
|
||||
return !!(context.hookEventName && context.sessionId && typeof context.success === 'boolean');
|
||||
}
|
||||
|
||||
/**
|
||||
* Gets the project name for this orchestrator instance
|
||||
*/
|
||||
public getProjectName(): string {
|
||||
return this.projectName;
|
||||
}
|
||||
|
||||
/**
|
||||
* Sets a new project name for this orchestrator instance
|
||||
*/
|
||||
public setProjectName(projectName: string): void {
|
||||
this.projectName = projectName;
|
||||
}
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// FACTORY FUNCTIONS
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Creates a new PromptOrchestrator instance
|
||||
*/
|
||||
export function createPromptOrchestrator(projectName?: string): PromptOrchestrator {
|
||||
return new PromptOrchestrator(projectName);
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates an analysis context from basic parameters
|
||||
*/
|
||||
export function createAnalysisContext(
|
||||
transcriptContent: string,
|
||||
sessionId: string,
|
||||
options: Partial<Omit<AnalysisContext, 'transcriptContent' | 'sessionId'>> = {}
|
||||
): AnalysisContext {
|
||||
return {
|
||||
transcriptContent,
|
||||
sessionId,
|
||||
...options,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates a session context from basic parameters
|
||||
*/
|
||||
export function createSessionContext(
|
||||
sessionId: string,
|
||||
source: SessionContext['source'],
|
||||
options: Partial<Omit<SessionContext, 'sessionId' | 'source'>> = {}
|
||||
): SessionContext {
|
||||
return {
|
||||
sessionId,
|
||||
source,
|
||||
...options,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates a hook context from basic parameters
|
||||
*/
|
||||
export function createHookContext(
|
||||
hookEventName: string,
|
||||
sessionId: string,
|
||||
success: boolean,
|
||||
options: Partial<Omit<HookContext, 'hookEventName' | 'sessionId' | 'success'>> = {}
|
||||
): HookContext {
|
||||
return {
|
||||
hookEventName,
|
||||
sessionId,
|
||||
success,
|
||||
...options,
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,128 @@
|
||||
import { query } from '@anthropic-ai/claude-code';
|
||||
import fs from 'fs';
|
||||
import path from 'path';
|
||||
import os from 'os';
|
||||
import { getClaudePath } from '../../shared/settings.js';
|
||||
|
||||
export interface TitleGenerationRequest {
|
||||
sessionId: string;
|
||||
projectName: string;
|
||||
firstMessage: string;
|
||||
}
|
||||
|
||||
export interface GeneratedTitle {
|
||||
session_id: string;
|
||||
generated_title: string;
|
||||
timestamp: string;
|
||||
project_name: string;
|
||||
}
|
||||
|
||||
export class TitleGenerator {
|
||||
private titlesIndexPath: string;
|
||||
|
||||
constructor() {
|
||||
this.titlesIndexPath = path.join(os.homedir(), '.claude-mem', 'conversation-titles.jsonl');
|
||||
this.ensureTitlesIndex();
|
||||
}
|
||||
|
||||
private ensureTitlesIndex(): void {
|
||||
const dir = path.dirname(this.titlesIndexPath);
|
||||
if (!fs.existsSync(dir)) {
|
||||
fs.mkdirSync(dir, { recursive: true });
|
||||
}
|
||||
if (!fs.existsSync(this.titlesIndexPath)) {
|
||||
fs.writeFileSync(this.titlesIndexPath, '', 'utf-8');
|
||||
}
|
||||
}
|
||||
|
||||
async generateTitle(firstMessage: string): Promise<string> {
|
||||
const prompt = `Generate a 3-7 word descriptive title for this conversation based on the first message.
|
||||
|
||||
The title should:
|
||||
- Capture the main topic or intent
|
||||
- Be concise and descriptive
|
||||
- Use proper capitalization
|
||||
- Not include "Help with" or "Question about" prefixes
|
||||
|
||||
First message: "${firstMessage.substring(0, 500)}"
|
||||
|
||||
Respond with just the title, nothing else.`;
|
||||
|
||||
const response = await query({
|
||||
prompt,
|
||||
options: {
|
||||
model: 'claude-3-5-haiku-20241022',
|
||||
pathToClaudeCodeExecutable: getClaudePath(),
|
||||
},
|
||||
});
|
||||
|
||||
let title = '';
|
||||
if (response && typeof response === 'object' && Symbol.asyncIterator in response) {
|
||||
for await (const message of response) {
|
||||
if (message?.content) title += message.content;
|
||||
if (message?.text) title += message.text;
|
||||
}
|
||||
} else if (typeof response === 'string') {
|
||||
title = response;
|
||||
}
|
||||
|
||||
return title.trim().replace(/^["']|["']$/g, '');
|
||||
}
|
||||
|
||||
async batchGenerateTitles(requests: TitleGenerationRequest[]): Promise<GeneratedTitle[]> {
|
||||
const results: GeneratedTitle[] = [];
|
||||
|
||||
for (const request of requests) {
|
||||
try {
|
||||
const title = await this.generateTitle(request.firstMessage);
|
||||
|
||||
const generatedTitle: GeneratedTitle = {
|
||||
session_id: request.sessionId,
|
||||
generated_title: title,
|
||||
timestamp: new Date().toISOString(),
|
||||
project_name: request.projectName
|
||||
};
|
||||
|
||||
results.push(generatedTitle);
|
||||
this.storeTitleInIndex(generatedTitle);
|
||||
} catch (error) {
|
||||
console.error(`Failed to generate title for ${request.sessionId}:`, error);
|
||||
}
|
||||
}
|
||||
|
||||
return results;
|
||||
}
|
||||
|
||||
private storeTitleInIndex(title: GeneratedTitle): void {
|
||||
const line = JSON.stringify(title) + '\n';
|
||||
fs.appendFileSync(this.titlesIndexPath, line, 'utf-8');
|
||||
}
|
||||
|
||||
getExistingTitles(): Map<string, GeneratedTitle> {
|
||||
const titles = new Map<string, GeneratedTitle>();
|
||||
|
||||
if (!fs.existsSync(this.titlesIndexPath)) {
|
||||
return titles;
|
||||
}
|
||||
|
||||
const content = fs.readFileSync(this.titlesIndexPath, 'utf-8');
|
||||
const lines = content.trim().split('\n').filter(Boolean);
|
||||
|
||||
for (const line of lines) {
|
||||
try {
|
||||
const title = JSON.parse(line) as GeneratedTitle;
|
||||
titles.set(title.session_id, title);
|
||||
} catch (error) {
|
||||
// Skip invalid lines
|
||||
}
|
||||
}
|
||||
|
||||
return titles;
|
||||
}
|
||||
|
||||
getTitleForSession(sessionId: string): string | null {
|
||||
const titles = this.getExistingTitles();
|
||||
const title = titles.get(sessionId);
|
||||
return title ? title.generated_title : null;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,64 @@
|
||||
/**
|
||||
* Time utilities for formatting relative timestamps
|
||||
*/
|
||||
|
||||
export function formatRelativeTime(timestamp: string | Date): string {
|
||||
try {
|
||||
const date = timestamp instanceof Date ? timestamp : new Date(timestamp);
|
||||
const now = new Date();
|
||||
const diffMs = now.getTime() - date.getTime();
|
||||
const diffSeconds = Math.floor(diffMs / 1000);
|
||||
const diffMinutes = Math.floor(diffSeconds / 60);
|
||||
const diffHours = Math.floor(diffMinutes / 60);
|
||||
const diffDays = Math.floor(diffHours / 24);
|
||||
const diffWeeks = Math.floor(diffDays / 7);
|
||||
const diffMonths = Math.floor(diffDays / 30);
|
||||
|
||||
if (diffSeconds < 60) {
|
||||
return 'Just now';
|
||||
} else if (diffMinutes < 60) {
|
||||
return diffMinutes === 1 ? '1 minute ago' : `${diffMinutes} minutes ago`;
|
||||
} else if (diffHours < 24) {
|
||||
return diffHours === 1 ? '1 hour ago' : `${diffHours} hours ago`;
|
||||
} else if (diffDays === 1) {
|
||||
return 'Yesterday';
|
||||
} else if (diffDays < 7) {
|
||||
return `${diffDays} days ago`;
|
||||
} else if (diffWeeks === 1) {
|
||||
return '1 week ago';
|
||||
} else if (diffWeeks < 4) {
|
||||
return `${diffWeeks} weeks ago`;
|
||||
} else if (diffMonths === 1) {
|
||||
return '1 month ago';
|
||||
} else if (diffMonths < 12) {
|
||||
return `${diffMonths} months ago`;
|
||||
} else {
|
||||
const diffYears = Math.floor(diffMonths / 12);
|
||||
return diffYears === 1 ? '1 year ago' : `${diffYears} years ago`;
|
||||
}
|
||||
} catch (error) {
|
||||
// Return a fallback for invalid timestamps
|
||||
return 'Recently';
|
||||
}
|
||||
}
|
||||
|
||||
export function parseTimestamp(entry: any): Date | null {
|
||||
// Try multiple timestamp fields that might exist
|
||||
const possibleFields = ['timestamp', 'created_at', 'date', 'time'];
|
||||
|
||||
for (const field of possibleFields) {
|
||||
if (entry[field]) {
|
||||
try {
|
||||
const date = new Date(entry[field]);
|
||||
if (!isNaN(date.getTime())) {
|
||||
return date;
|
||||
}
|
||||
} catch {
|
||||
continue;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// If no valid timestamp found, return null
|
||||
return null;
|
||||
}
|
||||
@@ -0,0 +1,191 @@
|
||||
/**
|
||||
* Claude Memory System - Prompt-Related Constants and Templates
|
||||
*
|
||||
* This file contains all prompts, instructions, and output templates
|
||||
* for the analysis and context priming system.
|
||||
*/
|
||||
|
||||
import * as HookTemplates from './templates/hooks/HookTemplates.js';
|
||||
|
||||
// =============================================================================
|
||||
// ANALYSIS PROMPTS AND TEMPLATES
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Entity naming patterns for the knowledge graph
|
||||
*/
|
||||
export const ENTITY_NAMING_PATTERNS = {
|
||||
component: "Component_Name",
|
||||
decision: "Decision_Name",
|
||||
pattern: "Pattern_Name",
|
||||
tool: "Tool_Name",
|
||||
fix: "Fix_Name",
|
||||
workflow: "Workflow_Name"
|
||||
} as const;
|
||||
|
||||
/**
|
||||
* Available entity types for classification
|
||||
*/
|
||||
export const ENTITY_TYPES = {
|
||||
component: "component", // UI components, modules, services
|
||||
pattern: "pattern", // Architectural or design patterns
|
||||
workflow: "workflow", // Processes, pipelines, sequences
|
||||
integration: "integration", // APIs, external services, data sources
|
||||
concept: "concept", // Abstract ideas, methodologies, principles
|
||||
decision: "decision", // Design choices, trade-offs, solutions
|
||||
tool: "tool", // Utilities, libraries, development tools
|
||||
fix: "fix" // Bug fixes, patches, workarounds
|
||||
} as const;
|
||||
|
||||
/**
|
||||
* Standard observation fields for entities
|
||||
*/
|
||||
export const OBSERVATION_FIELDS = [
|
||||
"Core purpose: [what it fundamentally does]",
|
||||
"Brief description: [one-line summary for session-start display]",
|
||||
"Implementation: [key technical details, code patterns]",
|
||||
"Dependencies: [what it requires or builds upon]",
|
||||
"Usage context: [when/why it's used]",
|
||||
"Performance characteristics: [speed, reliability, constraints]",
|
||||
"Integration points: [how it connects to other systems]",
|
||||
"Keywords: [searchable terms for this concept]",
|
||||
"Decision rationale: [why this approach was chosen]",
|
||||
"Next steps: [what needs to be done next with this component]",
|
||||
"Files modified: [list of files changed]",
|
||||
"Tools used: [development tools/commands used]"
|
||||
] as const;
|
||||
|
||||
/**
|
||||
* Relationship types for creating meaningful entity connections
|
||||
*/
|
||||
export const RELATIONSHIP_TYPES = [
|
||||
"executes_via", "orchestrates_through", "validates_using",
|
||||
"provides_auth_to", "manages_state_for", "processes_events_from",
|
||||
"caches_data_from", "routes_requests_to", "transforms_data_for",
|
||||
"extends", "enhances_performance_of", "builds_upon",
|
||||
"fixes_issue_in", "replaces", "optimizes",
|
||||
"triggers_tool", "receives_result_from"
|
||||
] as const;
|
||||
|
||||
|
||||
|
||||
// =============================================================================
|
||||
// CONTEXT PRIMING TEMPLATES
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* System message templates for context priming
|
||||
*/
|
||||
export const CONTEXT_TEMPLATES = {
|
||||
PRIMARY_CONTEXT: (projectName: string) =>
|
||||
`Context primed for project: ${projectName}. Access memories with chroma_query_documents(["${projectName}*"]) or chroma_get_documents(["document_id"]).`,
|
||||
|
||||
RECENT_SESSIONS: (sessionList: string) =>
|
||||
`Recent sessions available: ${sessionList}`,
|
||||
|
||||
AVAILABLE_ENTITIES: (type: string, entities: string[], hasMore: boolean, moreCount: number) =>
|
||||
`Available ${type} entities: ${entities.join(', ')}${hasMore ? ` (+${moreCount} more)` : ''}`,
|
||||
|
||||
SESSION_START_HEADER: '🧠 Active Working Context from Previous Sessions:',
|
||||
SESSION_START_SEPARATOR: '═'.repeat(70),
|
||||
|
||||
RESUME_INSTRUCTIONS: `💡 TO RESUME: Load active components with chroma_get_documents(["<exact_document_ids>"])
|
||||
📊 TO EXPLORE: Search related work with chroma_query_documents(["<keywords>"])`
|
||||
} as const;
|
||||
|
||||
// =============================================================================
|
||||
// SESSION START OUTPUT TEMPLATES
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Session start formatting templates
|
||||
*/
|
||||
export const SESSION_START_TEMPLATES = {
|
||||
FOCUS_LINE: (focus: string) => `📌 CURRENT FOCUS: ${focus}`,
|
||||
LAST_WORKED: (timeAgo: string, projectName: string) => `Last worked: ${timeAgo} | Project: ${projectName}`,
|
||||
|
||||
SECTIONS: {
|
||||
COMPONENTS: '🎯 ACTIVE COMPONENTS (load these for context):',
|
||||
DECISIONS: '🔄 RECENT DECISIONS & PATTERNS:',
|
||||
TOOLS: '🛠️ TOOLS & INFRASTRUCTURE:',
|
||||
FIXES: '🐛 RECENT FIXES:',
|
||||
ACTIONS: '⚡ NEXT ACTIONS:'
|
||||
},
|
||||
|
||||
ACTION_PREFIX: '□ ',
|
||||
ENTITY_BULLET: '• '
|
||||
} as const;
|
||||
|
||||
/**
|
||||
* Time formatting for "time ago" displays
|
||||
*/
|
||||
export const TIME_FORMATS = {
|
||||
JUST_NOW: 'just now',
|
||||
HOURS_AGO: (hours: number) => `${hours} hour${hours > 1 ? 's' : ''} ago`,
|
||||
DAYS_AGO: (days: number) => `${days} day${days > 1 ? 's' : ''} ago`,
|
||||
RECENTLY: 'recently'
|
||||
} as const;
|
||||
|
||||
// =============================================================================
|
||||
// HOOK RESPONSE TEMPLATES
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Standard hook response structures for Claude Code integration
|
||||
*/
|
||||
export const HOOK_RESPONSES = {
|
||||
SUCCESS: (hookEventName: string, message: string) => ({
|
||||
hookSpecificOutput: {
|
||||
hookEventName,
|
||||
status: "success",
|
||||
message
|
||||
},
|
||||
suppressOutput: true
|
||||
}),
|
||||
|
||||
SKIPPED: (hookEventName: string, message: string) => ({
|
||||
hookSpecificOutput: {
|
||||
hookEventName,
|
||||
status: "skipped",
|
||||
message
|
||||
},
|
||||
suppressOutput: true
|
||||
}),
|
||||
|
||||
BLOCKED: (reason: string) => ({
|
||||
decision: "block",
|
||||
reason
|
||||
}),
|
||||
|
||||
CONTINUE: (hookEventName: string, additionalContext?: string) => ({
|
||||
continue: true,
|
||||
...(additionalContext && {
|
||||
hookSpecificOutput: {
|
||||
hookEventName,
|
||||
additionalContext
|
||||
}
|
||||
})
|
||||
}),
|
||||
|
||||
ERROR: (reason: string) => ({
|
||||
decision: "block",
|
||||
reason
|
||||
})
|
||||
} as const;
|
||||
|
||||
/**
|
||||
* Pre-defined hook messages
|
||||
*/
|
||||
export const HOOK_MESSAGES = {
|
||||
COMPRESSION_SUCCESS: "Memory compression completed successfully",
|
||||
COMPRESSION_FAILED: (stderr: string) => `Compression failed: ${stderr}`,
|
||||
CONTEXT_LOADED: "Project context loaded successfully",
|
||||
CONTEXT_SKIPPED: "Continuing session - context loading skipped",
|
||||
NO_TRANSCRIPT: "No transcript path provided",
|
||||
HOOK_ERROR: (error: string) => `Hook error: ${error}`
|
||||
} as const;
|
||||
|
||||
/**
|
||||
* Export hook templates for direct usage
|
||||
*/
|
||||
export { HookTemplates };
|
||||
@@ -0,0 +1,30 @@
|
||||
/**
|
||||
* Prompts Module - Single source of truth for all prompt generation
|
||||
*
|
||||
* This module provides a centralized system for generating prompts across
|
||||
* the claude-mem system. It includes the core PromptOrchestrator class
|
||||
* and all related TypeScript interfaces.
|
||||
*/
|
||||
|
||||
// Export all interfaces
|
||||
export type {
|
||||
AnalysisContext,
|
||||
SessionContext,
|
||||
HookContext,
|
||||
AnalysisPrompt,
|
||||
SessionPrompt,
|
||||
HookResponse,
|
||||
} from '../core/orchestration/PromptOrchestrator.js';
|
||||
|
||||
// Export the main class
|
||||
export {
|
||||
PromptOrchestrator,
|
||||
} from '../core/orchestration/PromptOrchestrator.js';
|
||||
|
||||
// Export factory functions
|
||||
export {
|
||||
createPromptOrchestrator,
|
||||
createAnalysisContext,
|
||||
createSessionContext,
|
||||
createHookContext,
|
||||
} from '../core/orchestration/PromptOrchestrator.js';
|
||||
@@ -0,0 +1,190 @@
|
||||
# Claude Memory Templates
|
||||
|
||||
This directory contains modular templates for the Claude Memory System, including LLM analysis prompts and system integration responses.
|
||||
|
||||
## Files
|
||||
|
||||
### AnalysisTemplates.ts
|
||||
The main template system for LLM analysis prompts. Contains clean, separated template functions for:
|
||||
|
||||
- **Entity extraction instructions** - Guidelines for identifying and categorizing technical entities
|
||||
- **Relationship mapping instructions** - Rules for creating meaningful connections between entities
|
||||
- **Output format specifications** - Exact format requirements for pipe-separated summaries
|
||||
- **Example outputs** - Sample outputs to guide the LLM
|
||||
- **MCP tool usage instructions** - Step-by-step MCP tool usage workflow
|
||||
- **Dynamic content injection helpers** - Functions for injecting project/session context
|
||||
|
||||
### HookTemplates.ts
|
||||
System integration templates for Claude Code hook responses. Provides standardized templates for:
|
||||
|
||||
- **Pre-compact hook responses** - Approve/block compression operations with proper formatting
|
||||
- **Session-start hook responses** - Load and format context with rich memory information
|
||||
- **Pre-tool use hook responses** - Security policies and permission controls
|
||||
- **Error handling templates** - User-friendly error messages with troubleshooting guidance
|
||||
- **Progress indicators** - Status updates for long-running operations
|
||||
- **Response validation** - Ensures compliance with Claude Code hook specifications
|
||||
|
||||
### ContextTemplates.ts
|
||||
Human-readable formatting templates for user-facing messages during memory operations.
|
||||
|
||||
### Legacy Templates
|
||||
- `analysis-template.txt` - Legacy mustache-style template (deprecated)
|
||||
- `session-start-template.txt` - Legacy mustache-style template (deprecated)
|
||||
|
||||
## Architecture
|
||||
|
||||
The new template system follows these principles:
|
||||
|
||||
1. **Pure Functions** - Each template function takes context and returns formatted strings
|
||||
2. **Modular Design** - Complex prompts are broken into focused, reusable components
|
||||
3. **Type Safety** - Full TypeScript support with proper interfaces
|
||||
4. **Context Injection** - Dynamic content injection through helper functions
|
||||
5. **Composable Templates** - Build complex prompts by combining template sections
|
||||
|
||||
## Usage
|
||||
|
||||
### Hook Templates Usage
|
||||
```typescript
|
||||
import {
|
||||
createPreCompactSuccessResponse,
|
||||
createSessionStartMemoryResponse,
|
||||
createPreToolUseAllowResponse,
|
||||
validateHookResponse
|
||||
} from './HookTemplates.js';
|
||||
|
||||
// Pre-compact hook: approve compression
|
||||
const preCompactResponse = createPreCompactSuccessResponse();
|
||||
console.log(JSON.stringify(preCompactResponse));
|
||||
// Output: {"continue": true, "suppressOutput": true}
|
||||
|
||||
// Session start hook: load context with memories
|
||||
const sessionResponse = createSessionStartMemoryResponse({
|
||||
projectName: 'claude-mem',
|
||||
memoryCount: 15,
|
||||
lastSessionTime: '2 hours ago',
|
||||
recentComponents: ['HookTemplates', 'PromptOrchestrator'],
|
||||
recentDecisions: ['Use TypeScript for type safety']
|
||||
});
|
||||
console.log(JSON.stringify(sessionResponse));
|
||||
|
||||
// Pre-tool use: allow memory tools
|
||||
const toolResponse = createPreToolUseAllowResponse('Memory operations are always permitted');
|
||||
console.log(JSON.stringify(toolResponse));
|
||||
|
||||
// Validate responses before sending
|
||||
const validation = validateHookResponse(preCompactResponse, 'PreCompact');
|
||||
if (!validation.isValid) {
|
||||
console.error('Invalid response:', validation.errors);
|
||||
}
|
||||
```
|
||||
|
||||
### Analysis Templates Usage
|
||||
```typescript
|
||||
import { buildCompleteAnalysisPrompt } from './AnalysisTemplates.js';
|
||||
|
||||
const prompt = buildCompleteAnalysisPrompt(
|
||||
'myproject', // projectPrefix
|
||||
'session123', // sessionId
|
||||
[], // toolUseChains
|
||||
'2024-01-01', // timestamp (optional)
|
||||
'archive.jsonl' // archiveFilename (optional)
|
||||
);
|
||||
```
|
||||
|
||||
### Individual Template Components
|
||||
```typescript
|
||||
import {
|
||||
createEntityExtractionInstructions,
|
||||
createOutputFormatSpecification,
|
||||
createExampleOutput
|
||||
} from './AnalysisTemplates.js';
|
||||
|
||||
// Get just the entity extraction guidelines
|
||||
const entityInstructions = createEntityExtractionInstructions('myproject');
|
||||
|
||||
// Get output format specification
|
||||
const outputFormat = createOutputFormatSpecification('2024-01-01', 'archive.jsonl');
|
||||
|
||||
// Get example output
|
||||
const examples = createExampleOutput('myproject', 'session123');
|
||||
```
|
||||
|
||||
### Context Injection
|
||||
```typescript
|
||||
import {
|
||||
injectProjectContext,
|
||||
injectSessionContext,
|
||||
validateTemplateContext
|
||||
} from './AnalysisTemplates.js';
|
||||
|
||||
// Validate context before using templates
|
||||
const context = { projectPrefix: 'myproject', sessionId: 'session123' };
|
||||
const errors = validateTemplateContext(context);
|
||||
if (errors.length > 0) {
|
||||
console.error('Invalid context:', errors);
|
||||
}
|
||||
|
||||
// Inject dynamic content into template strings
|
||||
let template = "Working on {{projectPrefix}} session {{sessionId}}";
|
||||
template = injectProjectContext(template, 'myproject');
|
||||
template = injectSessionContext(template, 'session123');
|
||||
```
|
||||
|
||||
## Template Sections
|
||||
|
||||
### Entity Extraction Instructions
|
||||
- Categories of entities to extract (components, patterns, decisions, etc.)
|
||||
- Naming conventions with project prefixes
|
||||
- Entity type classifications
|
||||
- Observation field templates
|
||||
|
||||
### Relationship Mapping
|
||||
- Available relationship types
|
||||
- Active-voice relationship guidelines
|
||||
- Graph connection strategies
|
||||
|
||||
### Output Format
|
||||
- Pipe-separated format specification
|
||||
- Required fields and exact values
|
||||
- Summary writing guidelines
|
||||
|
||||
### MCP Tool Usage
|
||||
- Step-by-step MCP tool workflow
|
||||
- Entity creation instructions
|
||||
- Relationship creation guidelines
|
||||
|
||||
### Critical Requirements
|
||||
- Entity count requirements (3-15 entities)
|
||||
- Relationship count requirements (5-20 relationships)
|
||||
- Output line requirements (3-10 summaries)
|
||||
- Format validation rules
|
||||
|
||||
## Benefits Over Legacy System
|
||||
|
||||
1. **Maintainability** - Separated concerns make individual sections easy to update
|
||||
2. **Testability** - Pure functions can be unit tested independently
|
||||
3. **Reusability** - Template components can be reused across different contexts
|
||||
4. **Debugging** - Easy to isolate issues to specific template sections
|
||||
5. **Type Safety** - Full TypeScript support prevents runtime template errors
|
||||
6. **Performance** - No string parsing overhead, direct function composition
|
||||
|
||||
## Migration from constants.ts
|
||||
|
||||
The massive `createAnalysisPrompt` function in `constants.ts` has been refactored into this modular system:
|
||||
|
||||
**Before** (130+ lines in single function):
|
||||
```typescript
|
||||
export function createAnalysisPrompt(...) {
|
||||
// Massive template string with embedded logic
|
||||
return `You are analyzing...${incrementalSection}${toolChains}...`;
|
||||
}
|
||||
```
|
||||
|
||||
**After** (clean delegation):
|
||||
```typescript
|
||||
export function createAnalysisPrompt(...) {
|
||||
return buildCompleteAnalysisPrompt(...);
|
||||
}
|
||||
```
|
||||
|
||||
This maintains backward compatibility while providing a much cleaner, more maintainable internal structure.
|
||||
@@ -0,0 +1,118 @@
|
||||
/**
|
||||
* Analysis Templates for LLM Instructions
|
||||
*
|
||||
* Generates prompts for extracting memories from conversations and storing in Chroma
|
||||
*/
|
||||
|
||||
import Handlebars from 'handlebars';
|
||||
|
||||
// =============================================================================
|
||||
// MAIN ANALYSIS PROMPT TEMPLATE
|
||||
// =============================================================================
|
||||
|
||||
const ANALYSIS_PROMPT = `You are analyzing a Claude Code conversation transcript to create memories using the Chroma MCP memory system.
|
||||
|
||||
YOUR TASK:
|
||||
1. Extract key learnings and accomplishments as natural language memories
|
||||
2. Store memories using mcp__claude-mem__chroma_add_documents
|
||||
3. Return a structured JSON response with the extracted summaries
|
||||
|
||||
WHAT TO EXTRACT:
|
||||
- Technical implementations (functions, classes, APIs, databases)
|
||||
- Design patterns and architectural decisions
|
||||
- Bug fixes and problem solutions
|
||||
- Workflows, processes, and integrations
|
||||
- Performance optimizations and improvements
|
||||
|
||||
STORAGE INSTRUCTIONS:
|
||||
Call mcp__claude-mem__chroma_add_documents with:
|
||||
- collection_name: "claude_memories"
|
||||
- documents: Array of natural language descriptions
|
||||
- ids: ["{{projectPrefix}}_{{sessionId}}_1", "{{projectPrefix}}_{{sessionId}}_2", ...]
|
||||
- metadatas: Array with fields:
|
||||
* type: component/pattern/workflow/integration/concept/decision/tool/fix
|
||||
* keywords: Comma-separated search terms
|
||||
* context: Brief situation description
|
||||
* timestamp: "{{timestamp}}"
|
||||
* session_id: "{{sessionId}}"
|
||||
|
||||
ERROR HANDLING:
|
||||
If you get "IDs already exist" errors, use mcp__claude-mem__chroma_update_documents instead.
|
||||
If any tool calls fail, continue and return the JSON response anyway.
|
||||
|
||||
Project: {{projectPrefix}}
|
||||
Session ID: {{sessionId}}
|
||||
|
||||
Conversation to compress:`;
|
||||
|
||||
// Compile template once
|
||||
const compiledAnalysisPrompt = Handlebars.compile(ANALYSIS_PROMPT, { noEscape: true });
|
||||
|
||||
// =============================================================================
|
||||
// MAIN API FUNCTIONS
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Creates the comprehensive analysis prompt for memory extraction
|
||||
*/
|
||||
export function buildComprehensiveAnalysisPrompt(
|
||||
projectPrefix: string,
|
||||
sessionId: string,
|
||||
timestamp?: string,
|
||||
archiveFilename?: string
|
||||
): string {
|
||||
const context = {
|
||||
projectPrefix,
|
||||
sessionId,
|
||||
timestamp: timestamp || new Date().toISOString(),
|
||||
archiveFilename: archiveFilename || `${sessionId}.jsonl.archive`
|
||||
};
|
||||
|
||||
return compiledAnalysisPrompt(context);
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates the analysis prompt
|
||||
*/
|
||||
export function createAnalysisPrompt(
|
||||
transcript: string,
|
||||
sessionId: string,
|
||||
projectPrefix: string,
|
||||
timestamp?: string
|
||||
): string {
|
||||
const prompt = buildComprehensiveAnalysisPrompt(
|
||||
projectPrefix,
|
||||
sessionId,
|
||||
timestamp
|
||||
);
|
||||
|
||||
const responseFormat = `
|
||||
|
||||
RESPONSE FORMAT:
|
||||
After storing memories in Chroma, return EXACTLY this JSON structure wrapped in tags:
|
||||
|
||||
<JSONResponse>
|
||||
{
|
||||
"overview": "2-3 sentence summary of session themes and accomplishments. Write for any developer to understand by organically defining jargon.",
|
||||
"summaries": [
|
||||
{
|
||||
"text": "What was accomplished (start with action verb)",
|
||||
"document_id": "${projectPrefix}_${sessionId}_1",
|
||||
"keywords": "comma, separated, terms",
|
||||
"timestamp": "${timestamp || new Date().toISOString()}",
|
||||
"archive": "${sessionId}.jsonl.archive"
|
||||
}
|
||||
]
|
||||
}
|
||||
</JSONResponse>
|
||||
|
||||
IMPORTANT:
|
||||
- Return 3-10 summaries based on conversation complexity
|
||||
- Each summary should correspond to a memory you attempted to store
|
||||
- If tool calls fail, still return the JSON response with summaries
|
||||
- The JSON must be valid and complete
|
||||
- Place NOTHING outside the <JSONResponse> tags
|
||||
- Do not include any explanatory text before or after the JSON`;
|
||||
|
||||
return prompt + '\n\n' + transcript + responseFormat;
|
||||
}
|
||||
@@ -0,0 +1,672 @@
|
||||
/**
|
||||
* Context Templates for Human-Readable Formatting
|
||||
*
|
||||
* Essential templates for user-facing messages in the memory system.
|
||||
* Focused on session start messages, error handling, and operation feedback.
|
||||
* Previously included Handlebars templates for session start formatting; current
|
||||
* version renders directly via console for clarity and performance.
|
||||
*/
|
||||
|
||||
import { formatRelativeTime, parseTimestamp } from '../../../lib/time-utils.js';
|
||||
|
||||
// =============================================================================
|
||||
// TERMINAL WIDTH & WORD WRAPPING
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Determines target wrap width based on:
|
||||
* 1) CLAUDE_MEM_WRAP_WIDTH env override
|
||||
* 2) TTY columns (capped at 120)
|
||||
* 3) Fallback default of 80
|
||||
*/
|
||||
function getWrapWidth(): number {
|
||||
const env = process.env.CLAUDE_MEM_WRAP_WIDTH;
|
||||
if (env) {
|
||||
const n = parseInt(env, 10);
|
||||
if (!Number.isNaN(n) && n > 40 && n <= 200) return n;
|
||||
}
|
||||
// Default to classic 80 columns unless overridden
|
||||
return 80;
|
||||
}
|
||||
|
||||
/**
|
||||
* Wrap a single logical line to the given width, preserving leading indentation.
|
||||
* Also avoids wrapping pure separator lines (====, ----, etc.).
|
||||
*/
|
||||
function wrapSingleLine(line: string, width: number): string {
|
||||
if (!line) return '';
|
||||
// Don't wrap long separator lines
|
||||
if (/^[\-=\u2014_\u2500\u2550]{5,}$/.test(line.trim())) return line;
|
||||
|
||||
// If already short enough, return as-is
|
||||
if (line.length <= width) return line;
|
||||
|
||||
const indentMatch = line.match(/^\s*/);
|
||||
const indent = indentMatch ? indentMatch[0] : '';
|
||||
const content = line.slice(indent.length);
|
||||
const avail = Math.max(10, width - indent.length); // keep some minimum
|
||||
|
||||
const words = content.split(/(\s+)/); // keep whitespace tokens
|
||||
const out: string[] = [];
|
||||
let current = '';
|
||||
|
||||
const pushLine = () => {
|
||||
out.push(indent + current.trimEnd());
|
||||
current = '';
|
||||
};
|
||||
|
||||
for (const token of words) {
|
||||
if (token === '') continue;
|
||||
// If token itself is longer than available width, hard-break it
|
||||
if (!/\s/.test(token) && token.length > avail) {
|
||||
if (current.trim().length > 0) pushLine();
|
||||
let start = 0;
|
||||
while (start < token.length) {
|
||||
const chunk = token.slice(start, start + avail);
|
||||
out.push(indent + chunk);
|
||||
start += avail;
|
||||
}
|
||||
current = '';
|
||||
continue;
|
||||
}
|
||||
|
||||
if (indent.length + current.length + token.length > width) {
|
||||
pushLine();
|
||||
}
|
||||
current += token;
|
||||
}
|
||||
|
||||
if (current.trim().length > 0 || out.length === 0) pushLine();
|
||||
return out.join('\n');
|
||||
}
|
||||
|
||||
/**
|
||||
* Wrap a block of text (possibly multi-line) to the given width.
|
||||
* Preserves blank lines and wraps each line independently.
|
||||
*/
|
||||
function wrapText(text: string, width: number): string {
|
||||
if (!text) return '';
|
||||
return text
|
||||
.split('\n')
|
||||
.map((line) => wrapSingleLine(line, width))
|
||||
.join('\n');
|
||||
}
|
||||
|
||||
/** Create a full-width horizontal line with the given character */
|
||||
function makeLine(char: string = '─', width: number = getWrapWidth()): string {
|
||||
if (!char || char.length === 0) char = '-';
|
||||
// Repeat and slice to exact width to avoid multi-column surprises
|
||||
return char.repeat(width).slice(0, width);
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// SESSION START MESSAGES
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Creates a welcoming session start message explaining what memories were loaded
|
||||
*/
|
||||
export function createSessionStartMessage(
|
||||
projectName: string,
|
||||
memoryCount: number,
|
||||
lastSessionTime?: string
|
||||
): string {
|
||||
const width = getWrapWidth();
|
||||
const timeInfo = lastSessionTime ? ` (last worked: ${lastSessionTime})` : '';
|
||||
|
||||
if (memoryCount === 0) {
|
||||
return wrapText(
|
||||
`🧠 Loading memories from previous sessions for ${projectName}${timeInfo}
|
||||
|
||||
No relevant memories found - this appears to be your first session or a new project area.
|
||||
|
||||
💡 Getting Started:
|
||||
• Start working and memories will be automatically created
|
||||
• At the end of your session, ask to compress and store the conversation
|
||||
• Next time you return, relevant context will be loaded automatically`,
|
||||
width
|
||||
);
|
||||
}
|
||||
|
||||
const memoryText =
|
||||
memoryCount === 1 ? 'relevant memory' : 'relevant memories';
|
||||
return wrapText(
|
||||
`🧠 Loading memories from previous sessions for ${projectName}${timeInfo}
|
||||
|
||||
Found ${memoryCount} ${memoryText} to help continue your work.`,
|
||||
width
|
||||
);
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// OPERATION MESSAGES
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Creates a loading message during context retrieval
|
||||
*/
|
||||
export function createLoadingMessage(operation: string): string {
|
||||
const operations: Record<string, string> = {
|
||||
searching: '🔍 Searching previous memories...',
|
||||
loading: '📚 Loading relevant context...',
|
||||
formatting: '✨ Organizing memories for display...',
|
||||
compressing: '🗜️ Compressing session transcript...',
|
||||
archiving: '📦 Archiving conversation...',
|
||||
};
|
||||
|
||||
const width = getWrapWidth();
|
||||
return wrapText(operations[operation] || `⏳ ${operation}...`, width);
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates a completion message after context operations
|
||||
*/
|
||||
export function createCompletionMessage(
|
||||
operation: string,
|
||||
count?: number,
|
||||
details?: string
|
||||
): string {
|
||||
const countInfo = count !== undefined ? ` (${count} items)` : '';
|
||||
const detailInfo = details ? `\n${details}` : '';
|
||||
const width = getWrapWidth();
|
||||
return wrapText(
|
||||
`✅ ${operation} completed successfully${countInfo}${detailInfo}`,
|
||||
width
|
||||
);
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// ERROR MESSAGES (USER-FRIENDLY)
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Creates user-friendly error messages with helpful suggestions
|
||||
*/
|
||||
export function createUserFriendlyError(
|
||||
operation: string,
|
||||
error: string,
|
||||
suggestion?: string
|
||||
): string {
|
||||
const suggestionText = suggestion ? `\n\n💡 ${suggestion}` : '';
|
||||
const width = getWrapWidth();
|
||||
return wrapText(
|
||||
`❌ ${operation} encountered an issue: ${error}${suggestionText}`,
|
||||
width
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Common error scenarios with built-in suggestions
|
||||
*/
|
||||
export const ERROR_SCENARIOS = {
|
||||
NO_MEMORIES: (projectName: string) => ({
|
||||
message: `No previous memories found for ${projectName}`,
|
||||
suggestion:
|
||||
'This appears to be your first session. Memories will be created as you work.',
|
||||
}),
|
||||
|
||||
CONNECTION_FAILED: () => ({
|
||||
message: 'Could not connect to memory system',
|
||||
suggestion:
|
||||
'Try restarting Claude Code or check if the MCP server is properly configured.',
|
||||
}),
|
||||
|
||||
SEARCH_FAILED: (query: string) => ({
|
||||
message: `Search for "${query}" didn't return any results`,
|
||||
suggestion:
|
||||
'Try using different keywords or check if memories exist for this project.',
|
||||
}),
|
||||
|
||||
LOAD_TIMEOUT: () => ({
|
||||
message: 'Memory loading timed out',
|
||||
suggestion:
|
||||
'The operation is taking longer than expected. You can continue without loaded context.',
|
||||
}),
|
||||
};
|
||||
|
||||
/**
|
||||
* Creates contextual error messages based on common scenarios
|
||||
*/
|
||||
export function createContextualError(
|
||||
scenario: keyof typeof ERROR_SCENARIOS,
|
||||
...args: string[]
|
||||
): string {
|
||||
const errorInfo = (ERROR_SCENARIOS[scenario] as any)(...args);
|
||||
return createUserFriendlyError(
|
||||
'Memory system',
|
||||
errorInfo.message,
|
||||
errorInfo.suggestion
|
||||
);
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// TIME AND DATE FORMATTING
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Formats timestamps into human-readable "time ago" format
|
||||
*/
|
||||
export function formatTimeAgo(timestamp: string | Date): string {
|
||||
const date = typeof timestamp === 'string' ? new Date(timestamp) : timestamp;
|
||||
const now = new Date();
|
||||
const diff = now.getTime() - date.getTime();
|
||||
|
||||
const minutes = Math.floor(diff / 60000);
|
||||
const hours = Math.floor(diff / 3600000);
|
||||
const days = Math.floor(diff / 86400000);
|
||||
|
||||
if (minutes < 1) return 'just now';
|
||||
if (minutes < 60) return `${minutes} minute${minutes > 1 ? 's' : ''} ago`;
|
||||
if (hours < 24) return `${hours} hour${hours > 1 ? 's' : ''} ago`;
|
||||
if (days < 7) return `${days} day${days > 1 ? 's' : ''} ago`;
|
||||
|
||||
return date.toLocaleDateString();
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates summary text for memory operations
|
||||
*/
|
||||
export function createOperationSummary(
|
||||
operation: 'compress' | 'load' | 'search' | 'archive',
|
||||
results: { count: number; duration?: number; details?: string }
|
||||
): string {
|
||||
const { count, duration, details } = results;
|
||||
const durationText = duration ? ` in ${duration}ms` : '';
|
||||
const detailsText = details ? ` - ${details}` : '';
|
||||
|
||||
const templates = {
|
||||
compress: `Compressed ${count} conversation turns${durationText}${detailsText}`,
|
||||
load: `Loaded ${count} relevant memories${durationText}${detailsText}`,
|
||||
search: `Found ${count} matching memories${durationText}${detailsText}`,
|
||||
archive: `Archived ${count} conversation segments${durationText}${detailsText}`,
|
||||
};
|
||||
|
||||
const width = getWrapWidth();
|
||||
return wrapText(`📊 ${templates[operation]}`, width);
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// SESSION START TEMPLATE SYSTEM (data processing only)
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Interface for memory entry data structure
|
||||
*/
|
||||
interface MemoryEntry {
|
||||
summary: string;
|
||||
keywords?: string;
|
||||
location?: string;
|
||||
sessionId?: string;
|
||||
number?: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Interface for grouped session memories
|
||||
*/
|
||||
interface SessionGroup {
|
||||
sessionId: string;
|
||||
memories: MemoryEntry[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Formats current date and time for session start
|
||||
*/
|
||||
export function formatCurrentDateTime(): string {
|
||||
const now = new Date();
|
||||
const currentDateTime = now.toLocaleString('en-US', {
|
||||
weekday: 'long',
|
||||
year: 'numeric',
|
||||
month: 'long',
|
||||
day: 'numeric',
|
||||
hour: '2-digit',
|
||||
minute: '2-digit',
|
||||
timeZoneName: 'short',
|
||||
});
|
||||
|
||||
return `Current Date / Time: ${currentDateTime}\n`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Extracts overview section from JSON objects
|
||||
* Looks for objects with type "overview" and matching project
|
||||
*/
|
||||
export function extractOverview(
|
||||
recentObjects: any[],
|
||||
projectName?: string
|
||||
): string | null {
|
||||
// Find overview objects
|
||||
const overviewObjects = recentObjects.filter(
|
||||
(obj) => obj.type === 'overview'
|
||||
);
|
||||
|
||||
if (overviewObjects.length === 0) {
|
||||
return null;
|
||||
}
|
||||
|
||||
// If project is specified, find overview for that project
|
||||
if (projectName) {
|
||||
const projectOverview = overviewObjects.find(
|
||||
(obj) => obj.project === projectName
|
||||
);
|
||||
if (projectOverview) {
|
||||
return projectOverview.content;
|
||||
}
|
||||
}
|
||||
|
||||
// Return the most recent overview if no project match
|
||||
return overviewObjects[overviewObjects.length - 1]?.content || null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Interface for overview with timestamp
|
||||
*/
|
||||
interface OverviewEntry {
|
||||
content: string;
|
||||
timestamp?: Date;
|
||||
timeAgo?: string;
|
||||
sessionId?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Interface for session-grouped overviews
|
||||
*/
|
||||
interface SessionOverviewGroup {
|
||||
sessionId: string;
|
||||
overviews: OverviewEntry[];
|
||||
earliestTimestamp?: Date;
|
||||
timeAgo?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Extracts multiple overviews with timestamps
|
||||
* Returns up to 'count' most recent overviews
|
||||
*/
|
||||
export function extractOverviews(
|
||||
recentObjects: any[],
|
||||
count: number = 3,
|
||||
projectName?: string
|
||||
): OverviewEntry[] {
|
||||
// Find overview objects
|
||||
const overviewObjects = recentObjects.filter(
|
||||
(obj) => obj.type === 'overview'
|
||||
);
|
||||
|
||||
if (overviewObjects.length === 0) {
|
||||
return [];
|
||||
}
|
||||
|
||||
// Filter by project if specified
|
||||
let filteredOverviews = overviewObjects;
|
||||
if (projectName) {
|
||||
filteredOverviews = overviewObjects.filter(
|
||||
(obj) => obj.project === projectName
|
||||
);
|
||||
|
||||
// Fall back to all overviews if no project match
|
||||
if (filteredOverviews.length === 0) {
|
||||
filteredOverviews = overviewObjects;
|
||||
}
|
||||
}
|
||||
|
||||
// Take the last 'count' overviews
|
||||
const recentOverviews = filteredOverviews.slice(-count);
|
||||
|
||||
// Process each overview with timestamp and session ID
|
||||
return recentOverviews.map((obj) => {
|
||||
const entry: OverviewEntry = {
|
||||
content: obj.content || '',
|
||||
sessionId: obj.sessionId || obj.session_id || 'unknown',
|
||||
};
|
||||
|
||||
// Try to parse timestamp
|
||||
const timestamp = parseTimestamp(obj);
|
||||
if (timestamp) {
|
||||
entry.timestamp = timestamp;
|
||||
entry.timeAgo = formatRelativeTime(timestamp);
|
||||
} else {
|
||||
// Fallback if no timestamp
|
||||
entry.timeAgo = 'Recently';
|
||||
}
|
||||
|
||||
return entry;
|
||||
}); // Show in original order (oldest to newest)
|
||||
}
|
||||
|
||||
/**
|
||||
* Pure data processing function - converts JSON objects into structured memory entries
|
||||
* No formatting is done here, only data parsing and cleaning
|
||||
*/
|
||||
export function processMemoryEntries(recentObjects: any[]): MemoryEntry[] {
|
||||
if (recentObjects.length === 0) {
|
||||
return [];
|
||||
}
|
||||
|
||||
// Filter only memory type objects and convert to MemoryEntry format
|
||||
return recentObjects
|
||||
.filter((obj) => obj.type === 'memory')
|
||||
.map((obj) => {
|
||||
const entry: MemoryEntry = {
|
||||
summary: obj.text || '',
|
||||
sessionId: obj.session_id || '',
|
||||
};
|
||||
|
||||
// Add optional fields if present
|
||||
if (obj.keywords) {
|
||||
entry.keywords = obj.keywords;
|
||||
}
|
||||
if (obj.document_id && !obj.document_id.includes('Session:')) {
|
||||
entry.location = obj.document_id;
|
||||
}
|
||||
|
||||
return entry;
|
||||
})
|
||||
.filter((entry) => entry.summary.length > 0);
|
||||
}
|
||||
|
||||
/**
|
||||
* Groups memories by session ID and adds numbering
|
||||
*/
|
||||
function groupMemoriesBySession(memories: MemoryEntry[]): SessionGroup[] {
|
||||
const sessionMap = new Map<string, MemoryEntry[]>();
|
||||
|
||||
// Group memories by session ID
|
||||
memories.forEach((memory) => {
|
||||
const sessionId = memory.sessionId;
|
||||
if (sessionId) {
|
||||
if (!sessionMap.has(sessionId)) {
|
||||
sessionMap.set(sessionId, []);
|
||||
}
|
||||
sessionMap.get(sessionId)!.push(memory);
|
||||
}
|
||||
});
|
||||
|
||||
// Convert to session groups with numbering
|
||||
return Array.from(sessionMap.entries()).map(
|
||||
([sessionId, sessionMemories]) => {
|
||||
const numberedMemories = sessionMemories.map((memory, index) => ({
|
||||
...memory,
|
||||
number: index + 1,
|
||||
}));
|
||||
|
||||
return {
|
||||
sessionId,
|
||||
memories: numberedMemories,
|
||||
};
|
||||
}
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Groups overviews by session ID and calculates session timestamps
|
||||
*/
|
||||
function groupOverviewsBySession(
|
||||
overviews: OverviewEntry[]
|
||||
): SessionOverviewGroup[] {
|
||||
const sessionMap = new Map<string, OverviewEntry[]>();
|
||||
|
||||
// Group overviews by session ID
|
||||
overviews.forEach((overview) => {
|
||||
const sessionId = overview.sessionId || 'unknown';
|
||||
if (!sessionMap.has(sessionId)) {
|
||||
sessionMap.set(sessionId, []);
|
||||
}
|
||||
sessionMap.get(sessionId)!.push(overview);
|
||||
});
|
||||
|
||||
// Convert to session groups with timestamps
|
||||
return Array.from(sessionMap.entries()).map(
|
||||
([sessionId, sessionOverviews]) => {
|
||||
// Find the earliest timestamp in this session's overviews
|
||||
const timestamps = sessionOverviews
|
||||
.map((o) => o.timestamp)
|
||||
.filter((t): t is Date => t !== undefined)
|
||||
.sort((a, b) => a.getTime() - b.getTime());
|
||||
|
||||
const group: SessionOverviewGroup = {
|
||||
sessionId,
|
||||
overviews: sessionOverviews,
|
||||
};
|
||||
|
||||
// Add session-level timestamp if available
|
||||
if (timestamps.length > 0) {
|
||||
group.earliestTimestamp = timestamps[0];
|
||||
group.timeAgo = formatRelativeTime(timestamps[0]);
|
||||
}
|
||||
|
||||
return group;
|
||||
}
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Renders the complete session start template with provided data using Handlebars
|
||||
* Data processing is separated from presentation - template controls the format
|
||||
*/
|
||||
// Intentionally removed Handlebars-based renderer; console output is handled by
|
||||
// outputSessionStartContent() below.
|
||||
|
||||
/**
|
||||
* Outputs session start content using dual streams:
|
||||
* - stdout (console.log) -> Claude's context only (granular memories)
|
||||
* - stderr (console.error) -> User visible (clean overviews)
|
||||
*/
|
||||
export function outputSessionStartContent(params: {
|
||||
projectName: string;
|
||||
memoryCount: number;
|
||||
lastSessionTime?: string;
|
||||
recentObjects: any[];
|
||||
}): void {
|
||||
const { projectName, memoryCount, lastSessionTime, recentObjects } = params;
|
||||
const width = getWrapWidth();
|
||||
|
||||
// Start with current date and time at the top
|
||||
const now = new Date();
|
||||
const dateTimeFormatted = now.toLocaleString('en-US', {
|
||||
weekday: 'long',
|
||||
year: 'numeric',
|
||||
month: 'long',
|
||||
day: 'numeric',
|
||||
hour: '2-digit',
|
||||
minute: '2-digit',
|
||||
timeZoneName: 'short',
|
||||
});
|
||||
|
||||
console.log('');
|
||||
console.log(wrapText(`📅 ${dateTimeFormatted}`, width));
|
||||
console.log(makeLine('─', width));
|
||||
|
||||
// Extract overviews for user display - get more to show session grouping
|
||||
const overviews = extractOverviews(recentObjects, 10, projectName);
|
||||
|
||||
// Debug: Log what we're getting
|
||||
console.error(`[DEBUG] recentObjects has ${recentObjects.length} items`);
|
||||
console.error(`[DEBUG] overviews extracted: ${overviews.length}`);
|
||||
|
||||
// Process memory entries for Claude context
|
||||
const memories = processMemoryEntries(recentObjects);
|
||||
// Helper to split and normalize keywords into a map (lowercased -> original)
|
||||
const splitKeywordsInto = (kw: string, dest: Map<string, string>) => {
|
||||
const tokens =
|
||||
kw.includes(',') || kw.includes('\n') ? kw.split(/[\n,]+/) : [kw];
|
||||
for (const t of tokens) {
|
||||
const trimmed = t.trim();
|
||||
if (!trimmed) continue;
|
||||
const key = trimmed.toLowerCase();
|
||||
if (!dest.has(key)) dest.set(key, trimmed);
|
||||
}
|
||||
};
|
||||
|
||||
// Output memories first, then overviews at bottom, all sorted oldest to newest
|
||||
if (memories.length > 0) {
|
||||
const sessionGroups = groupMemoriesBySession(memories);
|
||||
console.log('');
|
||||
console.log('');
|
||||
|
||||
console.log(wrapText('📚 Memories', width));
|
||||
sessionGroups.forEach((group) => {
|
||||
console.log(makeLine('─', width));
|
||||
|
||||
console.log('');
|
||||
|
||||
console.log(wrapText(`🔍 ${group.sessionId}`, width));
|
||||
|
||||
// Collect keywords for this session as we iterate its memories
|
||||
const groupKeywordMap = new Map<string, string>();
|
||||
|
||||
group.memories.forEach((memory) => {
|
||||
console.log('');
|
||||
console.log(wrapText(`${memory.number}. ${memory.summary}`, width));
|
||||
if (memory.keywords)
|
||||
splitKeywordsInto(memory.keywords, groupKeywordMap);
|
||||
});
|
||||
|
||||
// Print this session's aggregated keywords under the session block
|
||||
const groupKeywords = Array.from(groupKeywordMap.values());
|
||||
if (groupKeywords.length > 0) {
|
||||
console.log('');
|
||||
console.log(wrapText(`🏷️ ${groupKeywords.join(', ')}`, width));
|
||||
}
|
||||
console.log('');
|
||||
});
|
||||
}
|
||||
|
||||
// Overview section at bottom with session grouping
|
||||
if (overviews.length > 0) {
|
||||
const sessionGroups = groupOverviewsBySession(overviews);
|
||||
|
||||
// Sort groups by timestamp, oldest first for chronological reading order
|
||||
sessionGroups.sort((a, b) => {
|
||||
const timeA = a.earliestTimestamp?.getTime() || 0;
|
||||
const timeB = b.earliestTimestamp?.getTime() || 0;
|
||||
return timeA - timeB; // Ascending order (oldest first)
|
||||
});
|
||||
|
||||
console.log('');
|
||||
|
||||
console.log(wrapText('🧠 Overviews', width));
|
||||
console.log(makeLine('─', width));
|
||||
|
||||
// Match the memories section layout: session header, numbered items, per-session separator
|
||||
sessionGroups.forEach((group) => {
|
||||
console.log('');
|
||||
console.log(wrapText(`🔍 ${group.sessionId}`, width));
|
||||
|
||||
group.overviews.forEach((overview, index) => {
|
||||
console.log('');
|
||||
console.log(wrapText(`${index + 1}. ${overview.content}`, width));
|
||||
console.log('');
|
||||
|
||||
if (overview.timeAgo) {
|
||||
console.log(wrapText(`📅 ${overview.timeAgo}`, width));
|
||||
}
|
||||
});
|
||||
|
||||
console.log('');
|
||||
console.log(makeLine('─', width));
|
||||
});
|
||||
} else if (memories.length === 0) {
|
||||
console.log(
|
||||
wrapText(`🧠 No recent context found for ${projectName}`, width)
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,185 @@
|
||||
/**
|
||||
* Hook Templates Test
|
||||
*
|
||||
* Basic validation tests for hook response templates to ensure they
|
||||
* generate valid responses that conform to Claude Code's hook system.
|
||||
*/
|
||||
|
||||
import {
|
||||
createPreCompactSuccessResponse,
|
||||
createPreCompactBlockedResponse,
|
||||
createPreCompactApprovalResponse,
|
||||
createSessionStartSuccessResponse,
|
||||
createSessionStartEmptyResponse,
|
||||
createSessionStartErrorResponse,
|
||||
createSessionStartMemoryResponse,
|
||||
createPreToolUseAllowResponse,
|
||||
createPreToolUseDenyResponse,
|
||||
createPreToolUseAskResponse,
|
||||
createHookSuccessResponse,
|
||||
createHookErrorResponse,
|
||||
validateHookResponse,
|
||||
createContextualHookResponse,
|
||||
formatDuration,
|
||||
createOperationSummary,
|
||||
OPERATION_STATUS_TEMPLATES,
|
||||
ERROR_RESPONSE_TEMPLATES
|
||||
} from './HookTemplates.js';
|
||||
|
||||
// =============================================================================
|
||||
// PRE-COMPACT HOOK TESTS
|
||||
// =============================================================================
|
||||
|
||||
console.log('Testing Pre-Compact Hook Templates...');
|
||||
|
||||
// Test successful pre-compact response
|
||||
const preCompactSuccess = createPreCompactSuccessResponse();
|
||||
console.log('✓ Pre-compact success:', JSON.stringify(preCompactSuccess, null, 2));
|
||||
|
||||
// Test blocked pre-compact response
|
||||
const preCompactBlocked = createPreCompactBlockedResponse('User requested to skip compression');
|
||||
console.log('✓ Pre-compact blocked:', JSON.stringify(preCompactBlocked, null, 2));
|
||||
|
||||
// Test approval response
|
||||
const preCompactApproval = createPreCompactApprovalResponse('approve', 'Compression approved by policy');
|
||||
console.log('✓ Pre-compact approval:', JSON.stringify(preCompactApproval, null, 2));
|
||||
|
||||
// =============================================================================
|
||||
// SESSION START HOOK TESTS
|
||||
// =============================================================================
|
||||
|
||||
console.log('\nTesting Session Start Hook Templates...');
|
||||
|
||||
// Test successful session start with context
|
||||
const sessionStartSuccess = createSessionStartSuccessResponse('Loaded 5 memories from previous sessions');
|
||||
console.log('✓ Session start success:', JSON.stringify(sessionStartSuccess, null, 2));
|
||||
|
||||
// Test empty session start
|
||||
const sessionStartEmpty = createSessionStartEmptyResponse();
|
||||
console.log('✓ Session start empty:', JSON.stringify(sessionStartEmpty, null, 2));
|
||||
|
||||
// Test error session start
|
||||
const sessionStartError = createSessionStartErrorResponse('Memory index corrupted');
|
||||
console.log('✓ Session start error:', JSON.stringify(sessionStartError, null, 2));
|
||||
|
||||
// Test rich memory response
|
||||
const sessionStartMemory = createSessionStartMemoryResponse({
|
||||
projectName: 'claude-mem',
|
||||
memoryCount: 12,
|
||||
lastSessionTime: '2 hours ago',
|
||||
recentComponents: ['PromptOrchestrator', 'HookTemplates', 'MCPClient'],
|
||||
recentDecisions: ['Use TypeScript for type safety', 'Implement embedded Weaviate']
|
||||
});
|
||||
console.log('✓ Session start memory:', JSON.stringify(sessionStartMemory, null, 2));
|
||||
|
||||
// =============================================================================
|
||||
// PRE-TOOL USE HOOK TESTS
|
||||
// =============================================================================
|
||||
|
||||
console.log('\nTesting Pre-Tool Use Hook Templates...');
|
||||
|
||||
// Test allow response
|
||||
const preToolAllow = createPreToolUseAllowResponse('Tool execution approved by security policy');
|
||||
console.log('✓ Pre-tool allow:', JSON.stringify(preToolAllow, null, 2));
|
||||
|
||||
// Test deny response
|
||||
const preToolDeny = createPreToolUseDenyResponse('Bash commands disabled in restricted mode');
|
||||
console.log('✓ Pre-tool deny:', JSON.stringify(preToolDeny, null, 2));
|
||||
|
||||
// Test ask response
|
||||
const preToolAsk = createPreToolUseAskResponse('File operation requires user confirmation');
|
||||
console.log('✓ Pre-tool ask:', JSON.stringify(preToolAsk, null, 2));
|
||||
|
||||
// =============================================================================
|
||||
// GENERIC HOOK TESTS
|
||||
// =============================================================================
|
||||
|
||||
console.log('\nTesting Generic Hook Templates...');
|
||||
|
||||
// Test basic success
|
||||
const genericSuccess = createHookSuccessResponse(false);
|
||||
console.log('✓ Generic success:', JSON.stringify(genericSuccess, null, 2));
|
||||
|
||||
// Test basic error
|
||||
const genericError = createHookErrorResponse('Operation failed due to network timeout', true);
|
||||
console.log('✓ Generic error:', JSON.stringify(genericError, null, 2));
|
||||
|
||||
// =============================================================================
|
||||
// VALIDATION TESTS
|
||||
// =============================================================================
|
||||
|
||||
console.log('\nTesting Hook Response Validation...');
|
||||
|
||||
// Test valid PreCompact response
|
||||
const preCompactValidation = validateHookResponse(preCompactSuccess, 'PreCompact');
|
||||
console.log('✓ PreCompact validation:', preCompactValidation);
|
||||
|
||||
// Test invalid PreCompact response (with hookSpecificOutput)
|
||||
const invalidPreCompact = {
|
||||
continue: true,
|
||||
hookSpecificOutput: { hookEventName: 'PreCompact' }
|
||||
};
|
||||
const preCompactInvalidValidation = validateHookResponse(invalidPreCompact, 'PreCompact');
|
||||
console.log('✓ PreCompact invalid validation:', preCompactInvalidValidation);
|
||||
|
||||
// Test valid SessionStart response
|
||||
const sessionStartValidation = validateHookResponse(sessionStartSuccess, 'SessionStart');
|
||||
console.log('✓ SessionStart validation:', sessionStartValidation);
|
||||
|
||||
// =============================================================================
|
||||
// CONTEXTUAL HOOK RESPONSE TESTS
|
||||
// =============================================================================
|
||||
|
||||
console.log('\nTesting Contextual Hook Responses...');
|
||||
|
||||
// Test successful session start context
|
||||
const contextualSessionStart = createContextualHookResponse({
|
||||
hookEventName: 'SessionStart',
|
||||
sessionId: 'test-123',
|
||||
success: true,
|
||||
message: 'Successfully loaded 8 memories from previous claude-mem sessions'
|
||||
});
|
||||
console.log('✓ Contextual SessionStart:', JSON.stringify(contextualSessionStart, null, 2));
|
||||
|
||||
// Test failed PreCompact context
|
||||
const contextualPreCompactFail = createContextualHookResponse({
|
||||
hookEventName: 'PreCompact',
|
||||
sessionId: 'test-123',
|
||||
success: false,
|
||||
message: 'Compression blocked: insufficient disk space'
|
||||
});
|
||||
console.log('✓ Contextual PreCompact fail:', JSON.stringify(contextualPreCompactFail, null, 2));
|
||||
|
||||
// =============================================================================
|
||||
// UTILITY FUNCTION TESTS
|
||||
// =============================================================================
|
||||
|
||||
console.log('\nTesting Utility Functions...');
|
||||
|
||||
// Test duration formatting
|
||||
console.log('✓ Duration 500ms:', formatDuration(500));
|
||||
console.log('✓ Duration 5s:', formatDuration(5000));
|
||||
console.log('✓ Duration 90s:', formatDuration(90000));
|
||||
console.log('✓ Duration 2m30s:', formatDuration(150000));
|
||||
|
||||
// Test operation summary
|
||||
console.log('✓ Operation summary success:', createOperationSummary('Memory compression', true, 5000, 15, 'entities extracted'));
|
||||
console.log('✓ Operation summary failure:', createOperationSummary('Context loading', false, 2000, 0, 'connection timeout'));
|
||||
|
||||
// =============================================================================
|
||||
// TEMPLATE CONSTANT TESTS
|
||||
// =============================================================================
|
||||
|
||||
console.log('\nTesting Template Constants...');
|
||||
|
||||
// Test operation status templates
|
||||
console.log('✓ Compression complete:', OPERATION_STATUS_TEMPLATES.COMPRESSION_COMPLETE(25, 5000));
|
||||
console.log('✓ Context loaded:', OPERATION_STATUS_TEMPLATES.CONTEXT_LOADED(8));
|
||||
console.log('✓ Tool allowed:', OPERATION_STATUS_TEMPLATES.TOOL_ALLOWED('Bash'));
|
||||
|
||||
// Test error response templates
|
||||
console.log('✓ File not found:', ERROR_RESPONSE_TEMPLATES.FILE_NOT_FOUND('/path/to/transcript.txt'));
|
||||
console.log('✓ Connection failed:', ERROR_RESPONSE_TEMPLATES.CONNECTION_FAILED('MCP memory server'));
|
||||
console.log('✓ Operation timeout:', ERROR_RESPONSE_TEMPLATES.OPERATION_TIMEOUT('compression', 30000));
|
||||
|
||||
console.log('\n✅ All hook template tests completed successfully!');
|
||||
@@ -0,0 +1,546 @@
|
||||
/**
|
||||
* Hook Templates for System Integration
|
||||
*
|
||||
* This module provides standardized templates for hook responses that integrate
|
||||
* with Claude Code's hook system. These templates ensure consistent formatting
|
||||
* and proper JSON structure for different hook events.
|
||||
*
|
||||
* Based on Claude Code Hook Documentation v2025
|
||||
*/
|
||||
|
||||
import {
|
||||
BaseHookResponse,
|
||||
PreCompactResponse,
|
||||
SessionStartResponse,
|
||||
PreToolUseResponse,
|
||||
HookPayload,
|
||||
PreCompactPayload,
|
||||
SessionStartPayload
|
||||
} from '../../../shared/types.js';
|
||||
|
||||
// =============================================================================
|
||||
// HOOK RESPONSE INTERFACES
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Context data for generating hook responses
|
||||
*/
|
||||
export interface HookResponseContext {
|
||||
/** The hook event name */
|
||||
hookEventName: string;
|
||||
/** Session identifier */
|
||||
sessionId: string;
|
||||
/** Whether the operation was successful */
|
||||
success: boolean;
|
||||
/** Optional message for the response */
|
||||
message?: string;
|
||||
/** Additional data specific to the hook type */
|
||||
additionalData?: Record<string, unknown>;
|
||||
/** Duration of the operation in milliseconds */
|
||||
duration?: number;
|
||||
/** Number of items processed */
|
||||
itemCount?: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Progress information for long-running operations
|
||||
*/
|
||||
export interface OperationProgress {
|
||||
/** Current step number */
|
||||
current: number;
|
||||
/** Total number of steps */
|
||||
total: number;
|
||||
/** Description of current step */
|
||||
currentStep?: string;
|
||||
/** Estimated time remaining in milliseconds */
|
||||
estimatedRemaining?: number;
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// PRE-COMPACT HOOK TEMPLATES
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Creates a successful pre-compact response that allows compression to proceed
|
||||
* PreCompact hooks do NOT support hookSpecificOutput according to documentation
|
||||
*/
|
||||
export function createPreCompactSuccessResponse(): PreCompactResponse {
|
||||
return {
|
||||
continue: true,
|
||||
suppressOutput: true
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates a blocked pre-compact response that prevents compression
|
||||
*/
|
||||
export function createPreCompactBlockedResponse(reason: string): PreCompactResponse {
|
||||
return {
|
||||
continue: false,
|
||||
stopReason: reason,
|
||||
suppressOutput: true
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates a pre-compact response with approval decision
|
||||
*/
|
||||
export function createPreCompactApprovalResponse(
|
||||
decision: 'approve' | 'block',
|
||||
reason?: string
|
||||
): PreCompactResponse {
|
||||
return {
|
||||
decision,
|
||||
reason,
|
||||
continue: decision === 'approve',
|
||||
suppressOutput: true
|
||||
};
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// SESSION START HOOK TEMPLATES
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Creates a successful session start response with loaded context
|
||||
* SessionStart hooks DO support hookSpecificOutput
|
||||
*/
|
||||
export function createSessionStartSuccessResponse(
|
||||
additionalContext?: string
|
||||
): SessionStartResponse {
|
||||
return {
|
||||
continue: true,
|
||||
suppressOutput: true,
|
||||
hookSpecificOutput: {
|
||||
hookEventName: 'SessionStart',
|
||||
additionalContext
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates a session start response when no context is available
|
||||
*/
|
||||
export function createSessionStartEmptyResponse(): SessionStartResponse {
|
||||
return {
|
||||
continue: true,
|
||||
suppressOutput: true,
|
||||
hookSpecificOutput: {
|
||||
hookEventName: 'SessionStart',
|
||||
additionalContext: 'Starting fresh session - no previous context available'
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates a session start response with error information
|
||||
*/
|
||||
export function createSessionStartErrorResponse(error: string): SessionStartResponse {
|
||||
return {
|
||||
continue: true, // Continue even if context loading fails
|
||||
suppressOutput: true,
|
||||
hookSpecificOutput: {
|
||||
hookEventName: 'SessionStart',
|
||||
additionalContext: `Context loading encountered an issue: ${error}. Starting without previous context.`
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates a rich session start response with memory summary
|
||||
*/
|
||||
export function createSessionStartMemoryResponse(memoryData: {
|
||||
projectName: string;
|
||||
memoryCount: number;
|
||||
lastSessionTime?: string;
|
||||
recentComponents?: string[];
|
||||
recentDecisions?: string[];
|
||||
}): SessionStartResponse {
|
||||
const { projectName, memoryCount, lastSessionTime, recentComponents = [], recentDecisions = [] } = memoryData;
|
||||
|
||||
const timeInfo = lastSessionTime ? ` (last worked: ${lastSessionTime})` : '';
|
||||
const contextParts: string[] = [];
|
||||
|
||||
contextParts.push(`🧠 Loaded ${memoryCount} memories from previous sessions for ${projectName}${timeInfo}`);
|
||||
|
||||
if (recentComponents.length > 0) {
|
||||
contextParts.push(`\n🎯 Recent components: ${recentComponents.slice(0, 3).join(', ')}`);
|
||||
}
|
||||
|
||||
if (recentDecisions.length > 0) {
|
||||
contextParts.push(`\n🔄 Recent decisions: ${recentDecisions.slice(0, 2).join(', ')}`);
|
||||
}
|
||||
|
||||
contextParts.push('\n💡 Use chroma_query_documents(["keywords"]) to find related work or chroma_get_documents(["document_id"]) to load specific content');
|
||||
|
||||
return {
|
||||
continue: true,
|
||||
suppressOutput: true,
|
||||
hookSpecificOutput: {
|
||||
hookEventName: 'SessionStart',
|
||||
additionalContext: contextParts.join('')
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// PRE-TOOL USE HOOK TEMPLATES
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Creates a pre-tool use response that allows the tool to execute
|
||||
*/
|
||||
export function createPreToolUseAllowResponse(reason?: string): PreToolUseResponse {
|
||||
return {
|
||||
continue: true,
|
||||
suppressOutput: true,
|
||||
permissionDecision: 'allow',
|
||||
permissionDecisionReason: reason
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates a pre-tool use response that blocks the tool execution
|
||||
*/
|
||||
export function createPreToolUseDenyResponse(reason: string): PreToolUseResponse {
|
||||
return {
|
||||
continue: false,
|
||||
stopReason: reason,
|
||||
suppressOutput: true,
|
||||
permissionDecision: 'deny',
|
||||
permissionDecisionReason: reason
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates a pre-tool use response that asks for user confirmation
|
||||
*/
|
||||
export function createPreToolUseAskResponse(reason: string): PreToolUseResponse {
|
||||
return {
|
||||
continue: true,
|
||||
suppressOutput: false, // Show output so user can see the question
|
||||
permissionDecision: 'ask',
|
||||
permissionDecisionReason: reason
|
||||
};
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// GENERIC HOOK RESPONSE TEMPLATES
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Creates a basic success response for any hook type
|
||||
*/
|
||||
export function createHookSuccessResponse(suppressOutput = true): BaseHookResponse {
|
||||
return {
|
||||
continue: true,
|
||||
suppressOutput
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates a basic error response for any hook type
|
||||
*/
|
||||
export function createHookErrorResponse(
|
||||
reason: string,
|
||||
suppressOutput = true
|
||||
): BaseHookResponse {
|
||||
return {
|
||||
continue: false,
|
||||
stopReason: reason,
|
||||
suppressOutput
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates a response with system message (warning/info for user)
|
||||
*/
|
||||
export function createHookSystemMessageResponse(
|
||||
message: string,
|
||||
continueProcessing = true
|
||||
): BaseHookResponse & { systemMessage: string } {
|
||||
return {
|
||||
continue: continueProcessing,
|
||||
suppressOutput: true,
|
||||
systemMessage: message
|
||||
};
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// OPERATION STATUS TEMPLATES
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Templates for different types of operation status messages
|
||||
*/
|
||||
export const OPERATION_STATUS_TEMPLATES = {
|
||||
// Compression operations
|
||||
COMPRESSION_STARTED: 'Starting memory compression...',
|
||||
COMPRESSION_ANALYZING: 'Analyzing transcript content...',
|
||||
COMPRESSION_EXTRACTING: 'Extracting memories and connections...',
|
||||
COMPRESSION_SAVING: 'Saving compressed memories...',
|
||||
COMPRESSION_COMPLETE: (count: number, duration?: number) =>
|
||||
`Memory compression complete. Extracted ${count} memories${duration ? ` in ${Math.round(duration/1000)}s` : ''}`,
|
||||
|
||||
// Context loading operations
|
||||
CONTEXT_LOADING: 'Loading previous session context...',
|
||||
CONTEXT_SEARCHING: 'Searching for relevant memories...',
|
||||
CONTEXT_FORMATTING: 'Organizing context for display...',
|
||||
CONTEXT_LOADED: (count: number) => `Context loaded successfully. Found ${count} relevant memories`,
|
||||
CONTEXT_EMPTY: 'No previous context found. Starting fresh session',
|
||||
|
||||
// Tool operations
|
||||
TOOL_CHECKING: (toolName: string) => `Checking permissions for ${toolName}...`,
|
||||
TOOL_ALLOWED: (toolName: string) => `✅ ${toolName} execution approved`,
|
||||
TOOL_BLOCKED: (toolName: string, reason: string) => `❌ ${toolName} blocked: ${reason}`,
|
||||
|
||||
// General operations
|
||||
OPERATION_STARTING: (operation: string) => `Starting ${operation}...`,
|
||||
OPERATION_PROGRESS: (operation: string, current: number, total: number) =>
|
||||
`${operation}: ${current}/${total} (${Math.round((current/total)*100)}%)`,
|
||||
OPERATION_COMPLETE: (operation: string) => `✅ ${operation} completed successfully`,
|
||||
OPERATION_FAILED: (operation: string, error: string) => `❌ ${operation} failed: ${error}`
|
||||
} as const;
|
||||
|
||||
/**
|
||||
* Creates a progress message for long-running operations
|
||||
*/
|
||||
export function createProgressMessage(
|
||||
operation: string,
|
||||
progress: OperationProgress
|
||||
): string {
|
||||
const { current, total, currentStep, estimatedRemaining } = progress;
|
||||
const percentage = Math.round((current / total) * 100);
|
||||
|
||||
let message = `${operation}: ${current}/${total} (${percentage}%)`;
|
||||
|
||||
if (currentStep) {
|
||||
message += ` - ${currentStep}`;
|
||||
}
|
||||
|
||||
if (estimatedRemaining && estimatedRemaining > 1000) {
|
||||
const seconds = Math.round(estimatedRemaining / 1000);
|
||||
message += ` (${seconds}s remaining)`;
|
||||
}
|
||||
|
||||
return message;
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// ERROR RESPONSE TEMPLATES
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Standard error messages for different failure scenarios
|
||||
*/
|
||||
export const ERROR_RESPONSE_TEMPLATES = {
|
||||
// File system errors
|
||||
FILE_NOT_FOUND: (path: string) => `File not found: ${path}`,
|
||||
FILE_READ_ERROR: (path: string, error: string) => `Failed to read ${path}: ${error}`,
|
||||
FILE_WRITE_ERROR: (path: string, error: string) => `Failed to write ${path}: ${error}`,
|
||||
|
||||
// Network/connection errors
|
||||
CONNECTION_FAILED: (service: string) => `Failed to connect to ${service}`,
|
||||
CONNECTION_TIMEOUT: (service: string) => `Connection to ${service} timed out`,
|
||||
|
||||
// Validation errors
|
||||
INVALID_PAYLOAD: (field: string) => `Invalid or missing field: ${field}`,
|
||||
INVALID_FORMAT: (expected: string, received: string) => `Expected ${expected}, received ${received}`,
|
||||
|
||||
// Operation errors
|
||||
OPERATION_TIMEOUT: (operation: string, timeout: number) =>
|
||||
`${operation} timed out after ${timeout}ms`,
|
||||
OPERATION_CANCELLED: (operation: string) => `${operation} was cancelled`,
|
||||
INSUFFICIENT_PERMISSIONS: (operation: string) =>
|
||||
`Insufficient permissions for ${operation}`,
|
||||
|
||||
// Memory system errors
|
||||
MEMORY_SYSTEM_UNAVAILABLE: 'Memory system is not available',
|
||||
MEMORY_CORRUPTION: 'Memory index appears to be corrupted',
|
||||
MEMORY_SEARCH_FAILED: (query: string) => `Memory search failed for query: "${query}"`,
|
||||
|
||||
// Compression errors
|
||||
COMPRESSION_FAILED: (stage: string) => `Compression failed during ${stage}`,
|
||||
INVALID_TRANSCRIPT: 'Transcript file is invalid or corrupted',
|
||||
|
||||
// General errors
|
||||
UNKNOWN_ERROR: (context: string) => `An unexpected error occurred during ${context}`,
|
||||
SYSTEM_ERROR: (error: string) => `System error: ${error}`
|
||||
} as const;
|
||||
|
||||
/**
|
||||
* Creates a standardized error response with troubleshooting guidance
|
||||
*/
|
||||
export function createDetailedErrorResponse(
|
||||
operation: string,
|
||||
error: string,
|
||||
troubleshootingSteps: string[] = []
|
||||
): BaseHookResponse {
|
||||
const baseMessage = `${operation} failed: ${error}`;
|
||||
|
||||
const fullMessage = troubleshootingSteps.length > 0
|
||||
? `${baseMessage}\n\nTroubleshooting steps:\n${troubleshootingSteps.map(step => `• ${step}`).join('\n')}`
|
||||
: baseMessage;
|
||||
|
||||
return {
|
||||
continue: false,
|
||||
stopReason: fullMessage,
|
||||
suppressOutput: false // Show error details to user
|
||||
};
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// HOOK RESPONSE VALIDATION
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Validates that a hook response conforms to Claude Code expectations
|
||||
*/
|
||||
export function validateHookResponse(
|
||||
response: any,
|
||||
hookType: string
|
||||
): { isValid: boolean; errors: string[] } {
|
||||
const errors: string[] = [];
|
||||
|
||||
// Check required fields
|
||||
if (typeof response !== 'object' || response === null) {
|
||||
errors.push('Response must be a valid JSON object');
|
||||
return { isValid: false, errors };
|
||||
}
|
||||
|
||||
// Validate continue field
|
||||
if (response.continue !== undefined && typeof response.continue !== 'boolean') {
|
||||
errors.push('continue field must be a boolean');
|
||||
}
|
||||
|
||||
// Validate suppressOutput field
|
||||
if (response.suppressOutput !== undefined && typeof response.suppressOutput !== 'boolean') {
|
||||
errors.push('suppressOutput field must be a boolean');
|
||||
}
|
||||
|
||||
// Validate stopReason field
|
||||
if (response.stopReason !== undefined && typeof response.stopReason !== 'string') {
|
||||
errors.push('stopReason field must be a string');
|
||||
}
|
||||
|
||||
// Hook-specific validations
|
||||
if (hookType === 'PreCompact') {
|
||||
// PreCompact should not have hookSpecificOutput
|
||||
if (response.hookSpecificOutput !== undefined) {
|
||||
errors.push('PreCompact hooks do not support hookSpecificOutput');
|
||||
}
|
||||
|
||||
// Validate decision field if present
|
||||
if (response.decision !== undefined && !['approve', 'block'].includes(response.decision)) {
|
||||
errors.push('decision field must be "approve" or "block"');
|
||||
}
|
||||
}
|
||||
|
||||
if (hookType === 'SessionStart') {
|
||||
// Validate hookSpecificOutput structure
|
||||
if (response.hookSpecificOutput) {
|
||||
const hso = response.hookSpecificOutput;
|
||||
if (hso.hookEventName !== 'SessionStart') {
|
||||
errors.push('hookSpecificOutput.hookEventName must be "SessionStart"');
|
||||
}
|
||||
if (hso.additionalContext !== undefined && typeof hso.additionalContext !== 'string') {
|
||||
errors.push('hookSpecificOutput.additionalContext must be a string');
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (hookType === 'PreToolUse') {
|
||||
// Validate permissionDecision field
|
||||
if (response.permissionDecision !== undefined) {
|
||||
if (!['allow', 'deny', 'ask'].includes(response.permissionDecision)) {
|
||||
errors.push('permissionDecision must be "allow", "deny", or "ask"');
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
isValid: errors.length === 0,
|
||||
errors
|
||||
};
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// UTILITY FUNCTIONS
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Creates a hook response based on context and automatically handles hook-specific formatting
|
||||
*/
|
||||
export function createContextualHookResponse(context: HookResponseContext): BaseHookResponse {
|
||||
const { hookEventName, success, message, additionalData, duration, itemCount } = context;
|
||||
|
||||
// Base response
|
||||
const response: BaseHookResponse = {
|
||||
continue: success,
|
||||
suppressOutput: true
|
||||
};
|
||||
|
||||
// Add failure reason if not successful
|
||||
if (!success && message) {
|
||||
response.stopReason = message;
|
||||
response.suppressOutput = false; // Show error to user
|
||||
}
|
||||
|
||||
// Handle hook-specific output
|
||||
if (success && hookEventName === 'SessionStart' && message) {
|
||||
return {
|
||||
...response,
|
||||
hookSpecificOutput: {
|
||||
hookEventName: 'SessionStart',
|
||||
additionalContext: message
|
||||
}
|
||||
} as SessionStartResponse;
|
||||
}
|
||||
|
||||
// Handle PreCompact approval
|
||||
if (hookEventName === 'PreCompact') {
|
||||
return {
|
||||
...response,
|
||||
decision: success ? 'approve' : 'block',
|
||||
reason: message
|
||||
} as PreCompactResponse;
|
||||
}
|
||||
|
||||
return response;
|
||||
}
|
||||
|
||||
/**
|
||||
* Formats duration in milliseconds to human-readable format
|
||||
*/
|
||||
export function formatDuration(milliseconds: number): string {
|
||||
if (milliseconds < 1000) {
|
||||
return `${milliseconds}ms`;
|
||||
}
|
||||
|
||||
const seconds = Math.round(milliseconds / 1000);
|
||||
if (seconds < 60) {
|
||||
return `${seconds}s`;
|
||||
}
|
||||
|
||||
const minutes = Math.floor(seconds / 60);
|
||||
const remainingSeconds = seconds % 60;
|
||||
return remainingSeconds > 0 ? `${minutes}m ${remainingSeconds}s` : `${minutes}m`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates a summary line for operation completion
|
||||
*/
|
||||
export function createOperationSummary(
|
||||
operation: string,
|
||||
success: boolean,
|
||||
duration?: number,
|
||||
itemCount?: number,
|
||||
details?: string
|
||||
): string {
|
||||
const status = success ? '✅' : '❌';
|
||||
const durationText = duration ? ` in ${formatDuration(duration)}` : '';
|
||||
const itemText = itemCount ? ` (${itemCount} items)` : '';
|
||||
const detailText = details ? ` - ${details}` : '';
|
||||
|
||||
return `${status} ${operation}${itemText}${durationText}${detailText}`;
|
||||
}
|
||||
@@ -0,0 +1,364 @@
|
||||
import * as p from '@clack/prompts';
|
||||
import { TranscriptParser } from './transcript-parser.js';
|
||||
import path from 'path';
|
||||
import fs from 'fs';
|
||||
|
||||
/**
|
||||
* Conversation item for selection UI
|
||||
*/
|
||||
export interface ConversationItem {
|
||||
filePath: string;
|
||||
sessionId: string;
|
||||
timestamp: string;
|
||||
messageCount: number;
|
||||
gitBranch?: string;
|
||||
cwd: string;
|
||||
fileSize: number;
|
||||
displayName: string;
|
||||
projectName: string;
|
||||
parsedDate: Date;
|
||||
relativeDate: string;
|
||||
dateGroup: string;
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* Selection result
|
||||
*/
|
||||
export interface SelectionResult {
|
||||
selectedFiles: string[];
|
||||
cancelled: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Interactive conversation selector service
|
||||
*/
|
||||
export class ConversationSelector {
|
||||
private parser: TranscriptParser;
|
||||
|
||||
constructor() {
|
||||
this.parser = new TranscriptParser();
|
||||
}
|
||||
|
||||
/**
|
||||
* Show interactive selection UI for conversations with improved flow
|
||||
*/
|
||||
async selectConversations(): Promise<SelectionResult> {
|
||||
p.intro('🧠 Claude History Import');
|
||||
|
||||
const s = p.spinner();
|
||||
s.start('Scanning for conversation files...');
|
||||
|
||||
const conversationFiles = await this.parser.scanConversationFiles();
|
||||
|
||||
if (conversationFiles.length === 0) {
|
||||
s.stop('❌ No conversation files found');
|
||||
p.outro('No conversation files found in Claude projects directory');
|
||||
return { selectedFiles: [], cancelled: true };
|
||||
}
|
||||
|
||||
// Get metadata for each file
|
||||
const conversations: ConversationItem[] = [];
|
||||
for (const filePath of conversationFiles) {
|
||||
try {
|
||||
const metadata = await this.parser.getConversationMetadata(filePath);
|
||||
const projectName = this.extractProjectName(filePath);
|
||||
const parsedDate = this.parseTimestamp(metadata.timestamp, filePath);
|
||||
const relativeDate = this.formatRelativeDate(parsedDate);
|
||||
const dateGroup = this.getDateGroup(parsedDate);
|
||||
|
||||
conversations.push({
|
||||
filePath,
|
||||
...metadata,
|
||||
projectName,
|
||||
parsedDate,
|
||||
relativeDate,
|
||||
dateGroup,
|
||||
displayName: this.createDisplayName(filePath, metadata)
|
||||
});
|
||||
} catch (e) {
|
||||
// Skip invalid files silently
|
||||
}
|
||||
}
|
||||
|
||||
if (conversations.length === 0) {
|
||||
s.stop('❌ No valid conversation files found');
|
||||
p.outro('No valid conversation files found');
|
||||
return { selectedFiles: [], cancelled: true };
|
||||
}
|
||||
|
||||
s.stop(`Found ${conversations.length} conversation files`);
|
||||
|
||||
// Sort by timestamp (newest first)
|
||||
conversations.sort((a, b) => b.parsedDate.getTime() - a.parsedDate.getTime());
|
||||
|
||||
// If there are too many conversations, offer filtering options first
|
||||
let filteredConversations = conversations;
|
||||
if (conversations.length > 100) {
|
||||
const filterChoice = await p.select({
|
||||
message: `Found ${conversations.length} conversations. How would you like to proceed?`,
|
||||
options: [
|
||||
{ value: 'recent', label: 'Show recent (last 50)', hint: 'Most recent conversations' },
|
||||
{ value: 'project', label: 'Filter by project', hint: 'Select specific project first' },
|
||||
{ value: 'all', label: 'Show all', hint: `Display all ${conversations.length} conversations` }
|
||||
]
|
||||
});
|
||||
|
||||
if (p.isCancel(filterChoice)) {
|
||||
p.cancel('Selection cancelled');
|
||||
return { selectedFiles: [], cancelled: true };
|
||||
}
|
||||
|
||||
if (filterChoice === 'recent') {
|
||||
filteredConversations = conversations.slice(0, 50);
|
||||
} else if (filterChoice === 'project') {
|
||||
const projectNames = [...new Set(conversations.map(c => c.projectName))].sort();
|
||||
const selectedProject = await p.select({
|
||||
message: 'Select project:',
|
||||
options: projectNames.map(project => {
|
||||
const count = conversations.filter(c => c.projectName === project).length;
|
||||
return {
|
||||
value: project,
|
||||
label: project,
|
||||
hint: `${count} conversation${count === 1 ? '' : 's'}`
|
||||
};
|
||||
})
|
||||
});
|
||||
|
||||
if (p.isCancel(selectedProject)) {
|
||||
p.cancel('Selection cancelled');
|
||||
return { selectedFiles: [], cancelled: true };
|
||||
}
|
||||
|
||||
filteredConversations = conversations.filter(c => c.projectName === selectedProject);
|
||||
}
|
||||
}
|
||||
|
||||
// Conversation selection
|
||||
const selectedConversations = await this.selectConversationsFromList(filteredConversations);
|
||||
if (!selectedConversations || selectedConversations.length === 0) {
|
||||
p.cancel('No conversations selected');
|
||||
return { selectedFiles: [], cancelled: true };
|
||||
}
|
||||
|
||||
// Confirmation
|
||||
const confirmed = await this.confirmSelection(selectedConversations);
|
||||
if (!confirmed) {
|
||||
p.cancel('Import cancelled');
|
||||
return { selectedFiles: [], cancelled: true };
|
||||
}
|
||||
|
||||
p.outro(`Ready to import ${selectedConversations.length} conversations`);
|
||||
return { selectedFiles: selectedConversations.map(c => c.filePath), cancelled: false };
|
||||
}
|
||||
|
||||
/**
|
||||
* Extract project name from file path
|
||||
*/
|
||||
private extractProjectName(filePath: string): string {
|
||||
return path.basename(path.dirname(filePath));
|
||||
}
|
||||
|
||||
/**
|
||||
* Safely parse timestamp with fallback to file modification time
|
||||
*/
|
||||
private parseTimestamp(timestamp: string | undefined, filePath: string): Date {
|
||||
// Try parsing the provided timestamp
|
||||
if (timestamp) {
|
||||
const date = new Date(timestamp);
|
||||
if (!isNaN(date.getTime())) {
|
||||
return date;
|
||||
}
|
||||
}
|
||||
|
||||
// Fallback to file modification time
|
||||
try {
|
||||
const stats = fs.statSync(filePath);
|
||||
return stats.mtime;
|
||||
} catch (e) {
|
||||
// Last resort: current time
|
||||
return new Date();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Format date as relative time (e.g., "2 days ago", "3 weeks ago")
|
||||
*/
|
||||
private formatRelativeDate(date: Date): string {
|
||||
const now = new Date();
|
||||
const diffMs = now.getTime() - date.getTime();
|
||||
const diffMinutes = Math.floor(diffMs / (1000 * 60));
|
||||
const diffHours = Math.floor(diffMs / (1000 * 60 * 60));
|
||||
const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24));
|
||||
const diffWeeks = Math.floor(diffDays / 7);
|
||||
const diffMonths = Math.floor(diffDays / 30);
|
||||
|
||||
if (diffMinutes < 1) return 'just now';
|
||||
if (diffMinutes < 60) return `${diffMinutes}m ago`;
|
||||
if (diffHours < 24) return `${diffHours}h ago`;
|
||||
if (diffDays < 7) return `${diffDays}d ago`;
|
||||
if (diffWeeks < 4) return `${diffWeeks}w ago`;
|
||||
if (diffMonths < 12) return `${diffMonths}mo ago`;
|
||||
|
||||
const diffYears = Math.floor(diffMonths / 12);
|
||||
return `${diffYears}y ago`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get date group for grouping conversations
|
||||
*/
|
||||
private getDateGroup(date: Date): string {
|
||||
const now = new Date();
|
||||
const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
|
||||
const yesterday = new Date(today.getTime() - 24 * 60 * 60 * 1000);
|
||||
const thisWeekStart = new Date(today.getTime() - today.getDay() * 24 * 60 * 60 * 1000);
|
||||
const lastWeekStart = new Date(thisWeekStart.getTime() - 7 * 24 * 60 * 60 * 1000);
|
||||
const thisMonthStart = new Date(now.getFullYear(), now.getMonth(), 1);
|
||||
|
||||
const conversationDate = new Date(date.getFullYear(), date.getMonth(), date.getDate());
|
||||
|
||||
if (conversationDate.getTime() >= today.getTime()) {
|
||||
return 'Today';
|
||||
} else if (conversationDate.getTime() >= yesterday.getTime()) {
|
||||
return 'Yesterday';
|
||||
} else if (conversationDate.getTime() >= thisWeekStart.getTime()) {
|
||||
return 'This Week';
|
||||
} else if (conversationDate.getTime() >= lastWeekStart.getTime()) {
|
||||
return 'Last Week';
|
||||
} else if (conversationDate.getTime() >= thisMonthStart.getTime()) {
|
||||
return 'This Month';
|
||||
} else {
|
||||
return 'Older';
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Create display name for conversation
|
||||
*/
|
||||
private createDisplayName(filePath: string, metadata: any): string {
|
||||
const parsedDate = this.parseTimestamp(metadata.timestamp, filePath);
|
||||
const relativeDate = this.formatRelativeDate(parsedDate);
|
||||
const sizeKB = Math.round(metadata.fileSize / 1024);
|
||||
const branchInfo = metadata.gitBranch ? `${metadata.gitBranch}` : '';
|
||||
|
||||
return `${relativeDate} • ${metadata.messageCount} msgs • ${sizeKB}KB${branchInfo ? ` • ${branchInfo}` : ''}`;
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* Select specific conversations from list
|
||||
*/
|
||||
private async selectConversationsFromList(
|
||||
conversations: ConversationItem[]
|
||||
): Promise<ConversationItem[] | null> {
|
||||
// Group conversations by date for better organization
|
||||
const groupedConversations = this.groupConversationsByDate(conversations);
|
||||
const options = this.createGroupedOptions(groupedConversations, conversations);
|
||||
|
||||
// Multi-select with select all/none shortcuts
|
||||
const selectedIndices = await p.multiselect({
|
||||
message: `Select conversations to import (${conversations.length} available, Space=toggle, Enter=confirm):`,
|
||||
options,
|
||||
required: false
|
||||
});
|
||||
|
||||
if (p.isCancel(selectedIndices)) return null;
|
||||
|
||||
// Return selected conversations
|
||||
const selected = selectedIndices as number[];
|
||||
if (selected.length === 0) {
|
||||
return [];
|
||||
}
|
||||
|
||||
return selected.map(i => conversations[i]);
|
||||
}
|
||||
|
||||
/**
|
||||
* Confirm selection before processing
|
||||
*/
|
||||
private async confirmSelection(conversations: ConversationItem[]): Promise<boolean> {
|
||||
const totalSize = conversations.reduce((sum, c) => sum + c.fileSize, 0);
|
||||
const sizeKB = Math.round(totalSize / 1024);
|
||||
const projects = [...new Set(conversations.map(c => c.projectName))];
|
||||
|
||||
const details = [
|
||||
`${conversations.length} conversation${conversations.length === 1 ? '' : 's'}`,
|
||||
`${projects.length} project${projects.length === 1 ? '' : 's'}: ${projects.join(', ')}`,
|
||||
`Total size: ${sizeKB}KB`
|
||||
].join('\n');
|
||||
|
||||
const confirmed = await p.confirm({
|
||||
message: `Ready to import:\n\n${details}\n\nContinue?`,
|
||||
initialValue: true
|
||||
});
|
||||
|
||||
return !p.isCancel(confirmed) && confirmed;
|
||||
}
|
||||
|
||||
/**
|
||||
* Group conversations by date sections
|
||||
*/
|
||||
private groupConversationsByDate(conversations: ConversationItem[]): Map<string, ConversationItem[]> {
|
||||
const groups = new Map<string, ConversationItem[]>();
|
||||
|
||||
for (const conv of conversations) {
|
||||
const group = conv.dateGroup;
|
||||
if (!groups.has(group)) {
|
||||
groups.set(group, []);
|
||||
}
|
||||
groups.get(group)!.push(conv);
|
||||
}
|
||||
|
||||
return groups;
|
||||
}
|
||||
|
||||
/**
|
||||
* Create options with date group headers
|
||||
*/
|
||||
private createGroupedOptions(groupedConversations: Map<string, ConversationItem[]>, allConversations: ConversationItem[]) {
|
||||
const options: any[] = [];
|
||||
|
||||
// Add hint at top about selecting all/none
|
||||
options.push({
|
||||
value: 'hint',
|
||||
label: '💡 Use Space to toggle, A to select all, I to invert',
|
||||
disabled: true
|
||||
});
|
||||
options.push({ value: 'separator-hint', label: '─'.repeat(60), disabled: true });
|
||||
|
||||
// Define order of groups
|
||||
const groupOrder = ['Today', 'Yesterday', 'This Week', 'Last Week', 'This Month', 'Older'];
|
||||
|
||||
for (const groupName of groupOrder) {
|
||||
const conversations = groupedConversations.get(groupName);
|
||||
if (!conversations || conversations.length === 0) continue;
|
||||
|
||||
// Add group header (disabled option for visual separation)
|
||||
if (options.length > 2) { // Account for hint and separator
|
||||
options.push({ value: `separator-${groupName}`, label: '─'.repeat(50), disabled: true });
|
||||
}
|
||||
options.push({
|
||||
value: `header-${groupName}`,
|
||||
label: `${groupName} (${conversations.length})`,
|
||||
disabled: true
|
||||
});
|
||||
|
||||
// Add conversations in this group
|
||||
for (const conv of conversations) {
|
||||
const index = allConversations.indexOf(conv);
|
||||
const projectInfo = conv.projectName ? `[${conv.projectName}]` : '';
|
||||
const workingDir = conv.cwd && conv.cwd !== 'undefined' ? path.basename(conv.cwd) : '';
|
||||
const hint = `${projectInfo} ${workingDir}`.trim() || (conv.gitBranch ? `Branch: ${conv.gitBranch}` : '');
|
||||
|
||||
options.push({
|
||||
value: index,
|
||||
label: ` ${conv.displayName}`,
|
||||
hint: hint
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
return options;
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,414 @@
|
||||
import { join, dirname, sep } from 'path';
|
||||
import { homedir } from 'os';
|
||||
import { existsSync, statSync } from 'fs';
|
||||
import { execSync } from 'child_process';
|
||||
import { fileURLToPath } from 'url';
|
||||
|
||||
/**
|
||||
* PathDiscovery Service - Central path resolution for claude-mem
|
||||
*
|
||||
* Handles dynamic discovery of all required paths across different installation scenarios:
|
||||
* - npm global installs, local installs, and development environments
|
||||
* - Cross-platform path resolution (Windows, macOS, Linux)
|
||||
* - Environment variable overrides for customization
|
||||
* - Package resource discovery (hooks, commands)
|
||||
*/
|
||||
export class PathDiscovery {
|
||||
private static instance: PathDiscovery | null = null;
|
||||
|
||||
// Cached paths for performance
|
||||
private _dataDirectory: string | null = null;
|
||||
private _packageRoot: string | null = null;
|
||||
private _claudeConfigDirectory: string | null = null;
|
||||
|
||||
/**
|
||||
* Get singleton instance
|
||||
*/
|
||||
static getInstance(): PathDiscovery {
|
||||
if (!PathDiscovery.instance) {
|
||||
PathDiscovery.instance = new PathDiscovery();
|
||||
}
|
||||
return PathDiscovery.instance;
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// DATA DIRECTORIES - Where claude-mem stores its data
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Base data directory for claude-mem
|
||||
* Environment override: CLAUDE_MEM_DATA_DIR
|
||||
*/
|
||||
getDataDirectory(): string {
|
||||
if (this._dataDirectory) return this._dataDirectory;
|
||||
|
||||
this._dataDirectory = process.env.CLAUDE_MEM_DATA_DIR || join(homedir(), '.claude-mem');
|
||||
return this._dataDirectory;
|
||||
}
|
||||
|
||||
/**
|
||||
* Archives directory for compressed sessions
|
||||
*/
|
||||
getArchivesDirectory(): string {
|
||||
return join(this.getDataDirectory(), 'archives');
|
||||
}
|
||||
|
||||
/**
|
||||
* Hooks directory where claude-mem hooks are installed
|
||||
*/
|
||||
getHooksDirectory(): string {
|
||||
return join(this.getDataDirectory(), 'hooks');
|
||||
}
|
||||
|
||||
/**
|
||||
* Logs directory for claude-mem operation logs
|
||||
*/
|
||||
getLogsDirectory(): string {
|
||||
return join(this.getDataDirectory(), 'logs');
|
||||
}
|
||||
|
||||
/**
|
||||
* Index directory for memory indexing
|
||||
*/
|
||||
getIndexDirectory(): string {
|
||||
return this.getDataDirectory();
|
||||
}
|
||||
|
||||
/**
|
||||
* Index file path for memory indexing
|
||||
*/
|
||||
getIndexPath(): string {
|
||||
return join(this.getIndexDirectory(), 'claude-mem-index.jsonl');
|
||||
}
|
||||
|
||||
/**
|
||||
* Trash directory for smart trash feature
|
||||
*/
|
||||
getTrashDirectory(): string {
|
||||
return join(this.getDataDirectory(), 'trash');
|
||||
}
|
||||
|
||||
/**
|
||||
* Backups directory for configuration backups
|
||||
*/
|
||||
getBackupsDirectory(): string {
|
||||
return join(this.getDataDirectory(), 'backups');
|
||||
}
|
||||
|
||||
/**
|
||||
* Chroma database directory
|
||||
*/
|
||||
getChromaDirectory(): string {
|
||||
return join(this.getDataDirectory(), 'chroma');
|
||||
}
|
||||
|
||||
/**
|
||||
* Project-specific archive directory
|
||||
*/
|
||||
getProjectArchiveDirectory(projectName: string): string {
|
||||
return join(this.getArchivesDirectory(), projectName);
|
||||
}
|
||||
|
||||
/**
|
||||
* User settings file path
|
||||
*/
|
||||
getUserSettingsPath(): string {
|
||||
return join(this.getDataDirectory(), 'settings.json');
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// CLAUDE INTEGRATION PATHS - Where Claude Code expects configuration
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Claude configuration directory
|
||||
* Environment override: CLAUDE_CONFIG_DIR
|
||||
*/
|
||||
getClaudeConfigDirectory(): string {
|
||||
if (this._claudeConfigDirectory) return this._claudeConfigDirectory;
|
||||
|
||||
this._claudeConfigDirectory = process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude');
|
||||
return this._claudeConfigDirectory;
|
||||
}
|
||||
|
||||
/**
|
||||
* Claude settings file path
|
||||
*/
|
||||
getClaudeSettingsPath(): string {
|
||||
return join(this.getClaudeConfigDirectory(), 'settings.json');
|
||||
}
|
||||
|
||||
/**
|
||||
* Claude commands directory where custom commands are installed
|
||||
*/
|
||||
getClaudeCommandsDirectory(): string {
|
||||
return join(this.getClaudeConfigDirectory(), 'commands');
|
||||
}
|
||||
|
||||
/**
|
||||
* CLAUDE.md instructions file path
|
||||
*/
|
||||
getClaudeMdPath(): string {
|
||||
return join(this.getClaudeConfigDirectory(), 'CLAUDE.md');
|
||||
}
|
||||
|
||||
/**
|
||||
* MCP configuration file path (user-level)
|
||||
*/
|
||||
getMcpConfigPath(): string {
|
||||
return join(homedir(), '.claude.json');
|
||||
}
|
||||
|
||||
/**
|
||||
* MCP configuration file path (project-level)
|
||||
*/
|
||||
getProjectMcpConfigPath(): string {
|
||||
return join(process.cwd(), '.mcp.json');
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// PACKAGE DISCOVERY - Find claude-mem package resources
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Discover the claude-mem package root directory
|
||||
*/
|
||||
getPackageRoot(): string {
|
||||
if (this._packageRoot) return this._packageRoot;
|
||||
|
||||
// Method 1: Try require.resolve for package.json
|
||||
try {
|
||||
const packageJsonPath = require.resolve('claude-mem/package.json');
|
||||
this._packageRoot = dirname(packageJsonPath);
|
||||
return this._packageRoot;
|
||||
} catch {}
|
||||
|
||||
// Method 2: Walk up from current module location
|
||||
const currentFile = fileURLToPath(import.meta.url);
|
||||
let currentDir = dirname(currentFile);
|
||||
|
||||
for (let i = 0; i < 10; i++) {
|
||||
const packageJsonPath = join(currentDir, 'package.json');
|
||||
if (existsSync(packageJsonPath)) {
|
||||
try {
|
||||
const packageJson = require(packageJsonPath);
|
||||
if (packageJson.name === 'claude-mem') {
|
||||
this._packageRoot = currentDir;
|
||||
return this._packageRoot;
|
||||
}
|
||||
} catch {}
|
||||
}
|
||||
|
||||
const parentDir = dirname(currentDir);
|
||||
if (parentDir === currentDir) break;
|
||||
currentDir = parentDir;
|
||||
}
|
||||
|
||||
// Method 3: Try npm list command
|
||||
try {
|
||||
const npmOutput = execSync('npm list -g claude-mem --json 2>/dev/null || npm list claude-mem --json 2>/dev/null', {
|
||||
encoding: 'utf8'
|
||||
});
|
||||
const npmData = JSON.parse(npmOutput);
|
||||
|
||||
if (npmData.dependencies?.['claude-mem']?.resolved) {
|
||||
this._packageRoot = dirname(npmData.dependencies['claude-mem'].resolved);
|
||||
return this._packageRoot;
|
||||
}
|
||||
} catch {}
|
||||
|
||||
throw new Error('Cannot locate claude-mem package root. Ensure claude-mem is properly installed.');
|
||||
}
|
||||
|
||||
/**
|
||||
* Find hooks directory in the installed package
|
||||
*/
|
||||
findPackageHooksDirectory(): string {
|
||||
const packageRoot = this.getPackageRoot();
|
||||
const hooksDir = join(packageRoot, 'hooks');
|
||||
|
||||
// Verify it contains expected hook files
|
||||
const requiredHooks = ['pre-compact.js', 'session-start.js'];
|
||||
for (const hookFile of requiredHooks) {
|
||||
if (!existsSync(join(hooksDir, hookFile))) {
|
||||
throw new Error(`Package hooks directory missing required file: ${hookFile}`);
|
||||
}
|
||||
}
|
||||
|
||||
return hooksDir;
|
||||
}
|
||||
|
||||
/**
|
||||
* Find commands directory in the installed package
|
||||
*/
|
||||
findPackageCommandsDirectory(): string {
|
||||
const packageRoot = this.getPackageRoot();
|
||||
const commandsDir = join(packageRoot, 'commands');
|
||||
|
||||
// Verify it contains expected command files
|
||||
const requiredCommands = ['save.md'];
|
||||
for (const commandFile of requiredCommands) {
|
||||
if (!existsSync(join(commandsDir, commandFile))) {
|
||||
throw new Error(`Package commands directory missing required file: ${commandFile}`);
|
||||
}
|
||||
}
|
||||
|
||||
return commandsDir;
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// UTILITY METHODS
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Ensure a directory exists, creating it if necessary
|
||||
*/
|
||||
ensureDirectory(dirPath: string): void {
|
||||
if (!existsSync(dirPath)) {
|
||||
require('fs').mkdirSync(dirPath, { recursive: true });
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Ensure multiple directories exist
|
||||
*/
|
||||
ensureDirectories(dirPaths: string[]): void {
|
||||
dirPaths.forEach(dirPath => this.ensureDirectory(dirPath));
|
||||
}
|
||||
|
||||
/**
|
||||
* Create all claude-mem data directories
|
||||
*/
|
||||
ensureAllDataDirectories(): void {
|
||||
this.ensureDirectories([
|
||||
this.getDataDirectory(),
|
||||
this.getArchivesDirectory(),
|
||||
this.getHooksDirectory(),
|
||||
this.getLogsDirectory(),
|
||||
this.getTrashDirectory(),
|
||||
this.getBackupsDirectory(),
|
||||
this.getChromaDirectory()
|
||||
]);
|
||||
}
|
||||
|
||||
/**
|
||||
* Create all Claude integration directories
|
||||
*/
|
||||
ensureAllClaudeDirectories(): void {
|
||||
this.ensureDirectories([
|
||||
this.getClaudeConfigDirectory(),
|
||||
this.getClaudeCommandsDirectory()
|
||||
]);
|
||||
}
|
||||
|
||||
/**
|
||||
* Extract project name from a file path (improved from PathResolver)
|
||||
*/
|
||||
static extractProjectName(filePath: string): string {
|
||||
const pathParts = filePath.split(sep);
|
||||
|
||||
// Look for common project indicators
|
||||
const projectIndicators = ['src', 'lib', 'app', 'project', 'workspace'];
|
||||
for (let i = pathParts.length - 1; i >= 0; i--) {
|
||||
if (projectIndicators.includes(pathParts[i]) && i > 0) {
|
||||
return pathParts[i - 1];
|
||||
}
|
||||
}
|
||||
|
||||
// Fallback to directory containing the file
|
||||
if (pathParts.length > 1) {
|
||||
return pathParts[pathParts.length - 2];
|
||||
}
|
||||
|
||||
return 'unknown-project';
|
||||
}
|
||||
|
||||
/**
|
||||
* Get current project directory name
|
||||
*/
|
||||
static getCurrentProjectName(): string {
|
||||
return require('path').basename(process.cwd());
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a timestamped backup filename
|
||||
*/
|
||||
static createBackupFilename(originalPath: string): string {
|
||||
const timestamp = new Date()
|
||||
.toISOString()
|
||||
.replace(/[:.]/g, '-')
|
||||
.replace('T', '_')
|
||||
.slice(0, 19);
|
||||
|
||||
return `${originalPath}.backup.${timestamp}`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if a path exists and is accessible
|
||||
*/
|
||||
static isPathAccessible(path: string): boolean {
|
||||
try {
|
||||
return existsSync(path) && statSync(path).isDirectory();
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// STATIC CONVENIENCE METHODS
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Quick access to singleton instance methods
|
||||
*/
|
||||
static getDataDirectory(): string {
|
||||
return PathDiscovery.getInstance().getDataDirectory();
|
||||
}
|
||||
|
||||
static getArchivesDirectory(): string {
|
||||
return PathDiscovery.getInstance().getArchivesDirectory();
|
||||
}
|
||||
|
||||
static getHooksDirectory(): string {
|
||||
return PathDiscovery.getInstance().getHooksDirectory();
|
||||
}
|
||||
|
||||
static getLogsDirectory(): string {
|
||||
return PathDiscovery.getInstance().getLogsDirectory();
|
||||
}
|
||||
|
||||
static getClaudeSettingsPath(): string {
|
||||
return PathDiscovery.getInstance().getClaudeSettingsPath();
|
||||
}
|
||||
|
||||
static getClaudeMdPath(): string {
|
||||
return PathDiscovery.getInstance().getClaudeMdPath();
|
||||
}
|
||||
|
||||
static findPackageHooksDirectory(): string {
|
||||
return PathDiscovery.getInstance().findPackageHooksDirectory();
|
||||
}
|
||||
|
||||
static findPackageCommandsDirectory(): string {
|
||||
return PathDiscovery.getInstance().findPackageCommandsDirectory();
|
||||
}
|
||||
}
|
||||
|
||||
// Export singleton instance for immediate use
|
||||
export const pathDiscovery = PathDiscovery.getInstance();
|
||||
|
||||
// Export static methods for convenience
|
||||
export const {
|
||||
getDataDirectory,
|
||||
getArchivesDirectory,
|
||||
getHooksDirectory,
|
||||
getLogsDirectory,
|
||||
getClaudeSettingsPath,
|
||||
getClaudeMdPath,
|
||||
findPackageHooksDirectory,
|
||||
findPackageCommandsDirectory,
|
||||
extractProjectName,
|
||||
getCurrentProjectName,
|
||||
createBackupFilename,
|
||||
isPathAccessible
|
||||
} = PathDiscovery;
|
||||
@@ -0,0 +1,218 @@
|
||||
import fs from 'fs';
|
||||
import path from 'path';
|
||||
import { log } from '../shared/logger.js';
|
||||
import { PathDiscovery } from './path-discovery.js';
|
||||
|
||||
/**
|
||||
* Interface for Claude Code JSONL conversation entries
|
||||
*/
|
||||
export interface ClaudeCodeMessage {
|
||||
sessionId: string;
|
||||
timestamp: string;
|
||||
gitBranch?: string;
|
||||
cwd: string;
|
||||
type: 'user' | 'assistant' | 'system' | 'result';
|
||||
message: {
|
||||
role: string;
|
||||
content: Array<{
|
||||
type: string;
|
||||
text?: string;
|
||||
thinking?: string;
|
||||
}> | string;
|
||||
};
|
||||
uuid: string;
|
||||
version?: string;
|
||||
isSidechain?: boolean;
|
||||
userType?: string;
|
||||
parentUuid?: string;
|
||||
subtype?: string;
|
||||
model?: string;
|
||||
stop_reason?: string;
|
||||
usage?: any;
|
||||
}
|
||||
|
||||
/**
|
||||
* Interface matching TranscriptCompressor's expected format
|
||||
*/
|
||||
export interface TranscriptMessage {
|
||||
type: string;
|
||||
message?: {
|
||||
content?: string | Array<{
|
||||
text?: string;
|
||||
content?: string;
|
||||
}>;
|
||||
role?: string;
|
||||
timestamp?: string;
|
||||
created_at?: string;
|
||||
};
|
||||
content?: string | Array<{
|
||||
text?: string;
|
||||
content?: string;
|
||||
}>;
|
||||
role?: string;
|
||||
uuid?: string;
|
||||
session_id?: string;
|
||||
timestamp?: string;
|
||||
created_at?: string;
|
||||
subtype?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Parsed conversation with metadata
|
||||
*/
|
||||
export interface ParsedConversation {
|
||||
sessionId: string;
|
||||
filePath: string;
|
||||
messageCount: number;
|
||||
timestamp: string;
|
||||
gitBranch?: string;
|
||||
cwd: string;
|
||||
messages: TranscriptMessage[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Service for parsing Claude Code JSONL conversation files
|
||||
*/
|
||||
export class TranscriptParser {
|
||||
|
||||
/**
|
||||
* Parse a single JSONL conversation file
|
||||
*/
|
||||
async parseConversation(filePath: string): Promise<ParsedConversation> {
|
||||
const content = fs.readFileSync(filePath, 'utf-8');
|
||||
const lines = content.trim().split('\n').filter(line => line.trim());
|
||||
|
||||
const claudeMessages: ClaudeCodeMessage[] = [];
|
||||
let parseErrors = 0;
|
||||
|
||||
for (let i = 0; i < lines.length; i++) {
|
||||
try {
|
||||
const parsed = JSON.parse(lines[i]);
|
||||
claudeMessages.push(parsed);
|
||||
} catch (e) {
|
||||
parseErrors++;
|
||||
log.debug(`Parse error on line ${i + 1}: ${(e as Error).message}`);
|
||||
}
|
||||
}
|
||||
|
||||
if (claudeMessages.length === 0) {
|
||||
throw new Error(`No valid messages found in ${filePath}`);
|
||||
}
|
||||
|
||||
// Get metadata from first message
|
||||
const firstMessage = claudeMessages[0];
|
||||
const sessionId = firstMessage.sessionId;
|
||||
const timestamp = firstMessage.timestamp;
|
||||
const gitBranch = firstMessage.gitBranch;
|
||||
const cwd = firstMessage.cwd;
|
||||
|
||||
// Convert to TranscriptMessage format
|
||||
const messages = claudeMessages.map(msg => this.convertMessage(msg));
|
||||
|
||||
log.debug(`Parsed ${filePath}: ${messages.length} messages, ${parseErrors} errors`);
|
||||
|
||||
return {
|
||||
sessionId,
|
||||
filePath,
|
||||
messageCount: messages.length,
|
||||
timestamp,
|
||||
gitBranch,
|
||||
cwd,
|
||||
messages
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Convert ClaudeCodeMessage to TranscriptMessage format
|
||||
*/
|
||||
private convertMessage(claudeMsg: ClaudeCodeMessage): TranscriptMessage {
|
||||
const converted: TranscriptMessage = {
|
||||
type: claudeMsg.type,
|
||||
uuid: claudeMsg.uuid,
|
||||
session_id: claudeMsg.sessionId,
|
||||
timestamp: claudeMsg.timestamp,
|
||||
subtype: claudeMsg.subtype
|
||||
};
|
||||
|
||||
// Handle message content
|
||||
if (claudeMsg.message) {
|
||||
converted.message = {
|
||||
role: claudeMsg.message.role,
|
||||
timestamp: claudeMsg.timestamp
|
||||
};
|
||||
|
||||
if (Array.isArray(claudeMsg.message.content)) {
|
||||
// Convert content array to expected format
|
||||
converted.message.content = claudeMsg.message.content.map(item => ({
|
||||
text: item.text || item.thinking || '',
|
||||
content: item.text || item.thinking || ''
|
||||
}));
|
||||
} else if (typeof claudeMsg.message.content === 'string') {
|
||||
converted.message.content = claudeMsg.message.content;
|
||||
}
|
||||
}
|
||||
|
||||
return converted;
|
||||
}
|
||||
|
||||
/**
|
||||
* Scan Claude projects directory for conversation files
|
||||
*/
|
||||
async scanConversationFiles(): Promise<string[]> {
|
||||
const pathDiscovery = PathDiscovery.getInstance();
|
||||
const claudeDir = path.join(pathDiscovery.getClaudeConfigDirectory(), 'projects');
|
||||
|
||||
if (!fs.existsSync(claudeDir)) {
|
||||
return [];
|
||||
}
|
||||
|
||||
const projectDirs = fs.readdirSync(claudeDir);
|
||||
const conversationFiles: string[] = [];
|
||||
|
||||
for (const projectDir of projectDirs) {
|
||||
const projectPath = path.join(claudeDir, projectDir);
|
||||
if (!fs.statSync(projectPath).isDirectory()) continue;
|
||||
|
||||
const files = fs.readdirSync(projectPath);
|
||||
for (const file of files) {
|
||||
if (file.endsWith('.jsonl')) {
|
||||
conversationFiles.push(path.join(projectPath, file));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return conversationFiles;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get conversation metadata without fully parsing
|
||||
*/
|
||||
async getConversationMetadata(filePath: string): Promise<{
|
||||
sessionId: string;
|
||||
timestamp: string;
|
||||
messageCount: number;
|
||||
gitBranch?: string;
|
||||
cwd: string;
|
||||
fileSize: number;
|
||||
}> {
|
||||
const stats = fs.statSync(filePath);
|
||||
const content = fs.readFileSync(filePath, 'utf-8');
|
||||
const lines = content.trim().split('\n').filter(line => line.trim());
|
||||
|
||||
let firstMessage;
|
||||
try {
|
||||
firstMessage = JSON.parse(lines[0]);
|
||||
} catch (e) {
|
||||
throw new Error(`Invalid JSONL format in ${filePath}`);
|
||||
}
|
||||
|
||||
return {
|
||||
sessionId: firstMessage.sessionId,
|
||||
timestamp: firstMessage.timestamp,
|
||||
messageCount: lines.length,
|
||||
gitBranch: firstMessage.gitBranch,
|
||||
cwd: firstMessage.cwd,
|
||||
fileSize: stats.size
|
||||
};
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,51 @@
|
||||
import { readFileSync, existsSync } from 'fs';
|
||||
import { join, dirname } from 'path';
|
||||
import { fileURLToPath } from 'url';
|
||||
|
||||
// <Block> 5.1 ====================================
|
||||
// Default values
|
||||
const DEFAULT_PACKAGE_NAME = 'claude-mem';
|
||||
// This MUST be replaced by build process with --define flag
|
||||
// @ts-ignore
|
||||
// For development, use fallback
|
||||
const DEFAULT_PACKAGE_VERSION = typeof __DEFAULT_PACKAGE_VERSION__ !== 'undefined'
|
||||
? __DEFAULT_PACKAGE_VERSION__
|
||||
: '3.5.6-dev';
|
||||
const DEFAULT_PACKAGE_DESCRIPTION = 'Memory compression system for Claude Code - persist context across sessions';
|
||||
|
||||
let packageName = DEFAULT_PACKAGE_NAME;
|
||||
let packageVersion = DEFAULT_PACKAGE_VERSION;
|
||||
let packageDescription = DEFAULT_PACKAGE_DESCRIPTION;
|
||||
// </Block> =======================================
|
||||
|
||||
// Try to read package.json if it exists (for development)
|
||||
// <Block> 5.2 ====================================
|
||||
try {
|
||||
const __filename = fileURLToPath(import.meta.url);
|
||||
const __dirname = dirname(__filename);
|
||||
const packageJsonPath = join(__dirname, '..', '..', 'package.json');
|
||||
|
||||
// <Block> 5.2a ====================================
|
||||
if (existsSync(packageJsonPath)) {
|
||||
const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
|
||||
// <Block> 5.2b ====================================
|
||||
packageName = packageJson.name || DEFAULT_PACKAGE_NAME;
|
||||
packageVersion = packageJson.version || DEFAULT_PACKAGE_VERSION;
|
||||
packageDescription = packageJson.description || DEFAULT_PACKAGE_DESCRIPTION;
|
||||
// </Block> =======================================
|
||||
}
|
||||
// </Block> =======================================
|
||||
} catch {
|
||||
// Use defaults if package.json can't be read
|
||||
}
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 5.3 ====================================
|
||||
// Export package configuration
|
||||
export const PACKAGE_NAME = packageName;
|
||||
export const PACKAGE_VERSION = packageVersion;
|
||||
export const PACKAGE_DESCRIPTION = packageDescription;
|
||||
|
||||
// Export commonly used names
|
||||
export const CLI_NAME = PACKAGE_NAME; // The CLI command name
|
||||
// </Block> =======================================
|
||||
@@ -0,0 +1,200 @@
|
||||
import { existsSync, mkdirSync } from 'fs';
|
||||
import { join, dirname } from 'path';
|
||||
import { fileURLToPath } from 'url';
|
||||
import { HookError, CompressionError, Logger, FileLogger } from './types.js';
|
||||
|
||||
const __filename = fileURLToPath(import.meta.url);
|
||||
const __dirname = dirname(__filename);
|
||||
|
||||
export class ErrorHandler {
|
||||
private logger: Logger;
|
||||
private logDir: string;
|
||||
|
||||
// <Block> 7.1 ====================================
|
||||
constructor(enableDebug = false) {
|
||||
this.logDir = join(__dirname, '..', 'logs');
|
||||
this.ensureLogDirectory();
|
||||
|
||||
const logFile = join(
|
||||
this.logDir,
|
||||
`claude-mem-${new Date().toISOString().slice(0, 10)}.log`
|
||||
);
|
||||
this.logger = new FileLogger(logFile, enableDebug);
|
||||
}
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 7.2 ====================================
|
||||
private ensureLogDirectory(): void {
|
||||
if (!existsSync(this.logDir)) {
|
||||
mkdirSync(this.logDir, { recursive: true });
|
||||
}
|
||||
}
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 7.3 ====================================
|
||||
handleHookError(error: Error, hookType: string, payload?: unknown): never {
|
||||
// <Block> 7.3a ====================================
|
||||
const hookError =
|
||||
error instanceof HookError
|
||||
? error
|
||||
: new HookError(
|
||||
error.message,
|
||||
hookType,
|
||||
payload as any,
|
||||
'HOOK_EXECUTION_ERROR'
|
||||
);
|
||||
// </Block> =======================================
|
||||
|
||||
this.logger.error(`Hook execution failed in ${hookType}`, hookError, {
|
||||
hookType,
|
||||
payload: payload ? JSON.stringify(payload) : undefined,
|
||||
});
|
||||
|
||||
console.log(
|
||||
JSON.stringify({
|
||||
continue: false,
|
||||
stopReason: `Hook error: ${hookError.message}`,
|
||||
error: {
|
||||
type: hookError.name,
|
||||
message: hookError.message,
|
||||
code: hookError.code,
|
||||
},
|
||||
})
|
||||
);
|
||||
|
||||
process.exit(1);
|
||||
}
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 7.4 ====================================
|
||||
handleCompressionError(
|
||||
error: Error,
|
||||
transcriptPath: string,
|
||||
stage: string
|
||||
): never {
|
||||
// <Block> 7.4a ====================================
|
||||
const compressionError =
|
||||
error instanceof CompressionError
|
||||
? error
|
||||
: new CompressionError(error.message, transcriptPath, stage as any);
|
||||
// </Block> =======================================
|
||||
|
||||
this.logger.error(`Compression failed during ${stage}`, compressionError, {
|
||||
transcriptPath,
|
||||
stage,
|
||||
});
|
||||
|
||||
console.error(`Compression error: ${compressionError.message}`);
|
||||
console.error(`Stage: ${stage}`);
|
||||
console.error(`Transcript: ${transcriptPath}`);
|
||||
|
||||
process.exit(1);
|
||||
}
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 7.5 ====================================
|
||||
handleValidationError(
|
||||
message: string,
|
||||
context?: Record<string, unknown>
|
||||
): never {
|
||||
this.logger.error('Validation error', undefined, { message, context });
|
||||
|
||||
console.error(`Validation error: ${message}`);
|
||||
// <Block> 7.5a ====================================
|
||||
if (context) {
|
||||
console.error('Context:', JSON.stringify(context, null, 2));
|
||||
}
|
||||
// </Block> =======================================
|
||||
|
||||
process.exit(1);
|
||||
}
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 7.6 ====================================
|
||||
logSuccess(operation: string, details?: Record<string, unknown>): void {
|
||||
this.logger.info(`Operation successful: ${operation}`, details);
|
||||
}
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 7.7 ====================================
|
||||
logWarning(message: string, details?: Record<string, unknown>): void {
|
||||
this.logger.warn(message, details);
|
||||
}
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 7.8 ====================================
|
||||
logDebug(message: string, details?: Record<string, unknown>): void {
|
||||
this.logger.debug(message, details);
|
||||
}
|
||||
// </Block> =======================================
|
||||
}
|
||||
|
||||
// <Block> 7.9 ====================================
|
||||
export function parseStdinJson<T = unknown>(input: string): T {
|
||||
try {
|
||||
return JSON.parse(input) as T;
|
||||
} catch (error) {
|
||||
throw new Error(
|
||||
`Failed to parse JSON input: ${error instanceof Error ? error.message : 'Unknown error'}`
|
||||
);
|
||||
}
|
||||
}
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 7.10 ===================================
|
||||
export async function safeExecute<T>(
|
||||
operation: () => Promise<T>,
|
||||
errorHandler: ErrorHandler,
|
||||
context: string
|
||||
): Promise<T> {
|
||||
try {
|
||||
return await operation();
|
||||
} catch (error) {
|
||||
const message = `Safe execution failed in ${context}: ${error instanceof Error ? error.message : String(error)}`;
|
||||
errorHandler.handleValidationError(message, { context, error });
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 7.11 ===================================
|
||||
export function validateFileExists(
|
||||
filePath: string,
|
||||
errorHandler: ErrorHandler
|
||||
): void {
|
||||
if (!existsSync(filePath)) {
|
||||
errorHandler.handleValidationError(`File not found: ${filePath}`, {
|
||||
filePath,
|
||||
});
|
||||
}
|
||||
}
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 7.12 ===================================
|
||||
/**
|
||||
* Creates a standardized hook response using HookTemplates
|
||||
* @deprecated Use HookTemplates.createHookSuccessResponse or createHookErrorResponse instead
|
||||
* This function is maintained for backward compatibility but should be replaced with HookTemplates.
|
||||
*/
|
||||
export function createHookResponse(
|
||||
success: boolean,
|
||||
data?: Record<string, unknown>
|
||||
): string {
|
||||
// Log deprecation warning in development mode
|
||||
if (process.env.NODE_ENV === 'development') {
|
||||
console.warn('createHookResponse in error-handler.ts is deprecated. Use HookTemplates.createHookSuccessResponse or createHookErrorResponse instead.');
|
||||
}
|
||||
|
||||
const response = {
|
||||
continue: success,
|
||||
suppressOutput: true, // Add standard suppressOutput field for Claude Code compatibility
|
||||
...data,
|
||||
};
|
||||
|
||||
return JSON.stringify(response);
|
||||
}
|
||||
// </Block> =======================================
|
||||
|
||||
export const globalErrorHandler = new ErrorHandler(
|
||||
process.env.DEBUG === 'true'
|
||||
);
|
||||
@@ -0,0 +1,67 @@
|
||||
/**
|
||||
* Simple logging utility for claude-mem
|
||||
*/
|
||||
|
||||
export interface LogLevel {
|
||||
DEBUG: number;
|
||||
INFO: number;
|
||||
WARN: number;
|
||||
ERROR: number;
|
||||
}
|
||||
|
||||
const LOG_LEVELS: LogLevel = {
|
||||
DEBUG: 0,
|
||||
INFO: 1,
|
||||
WARN: 2,
|
||||
ERROR: 3,
|
||||
};
|
||||
|
||||
class Logger {
|
||||
// <Block> 2.1 ====================================
|
||||
private level: number = LOG_LEVELS.INFO;
|
||||
|
||||
setLevel(level: keyof LogLevel): void {
|
||||
this.level = LOG_LEVELS[level];
|
||||
}
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 2.2 ====================================
|
||||
debug(message: string, ...args: any[]): void {
|
||||
if (this.level <= LOG_LEVELS.DEBUG) {
|
||||
console.debug(`[DEBUG] ${message}`, ...args);
|
||||
}
|
||||
}
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 2.3 ====================================
|
||||
info(message: string, ...args: any[]): void {
|
||||
if (this.level <= LOG_LEVELS.INFO) {
|
||||
console.info(`[INFO] ${message}`, ...args);
|
||||
}
|
||||
}
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 2.4 ====================================
|
||||
warn(message: string, ...args: any[]): void {
|
||||
if (this.level <= LOG_LEVELS.WARN) {
|
||||
console.warn(`[WARN] ${message}`, ...args);
|
||||
}
|
||||
}
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 2.5 ====================================
|
||||
error(message: string, error?: any, context?: any): void {
|
||||
if (this.level <= LOG_LEVELS.ERROR) {
|
||||
console.error(`[ERROR] ${message}`);
|
||||
if (error) {
|
||||
console.error(error);
|
||||
}
|
||||
if (context) {
|
||||
console.error('Context:', context);
|
||||
}
|
||||
}
|
||||
}
|
||||
// </Block> =======================================
|
||||
}
|
||||
|
||||
export const log = new Logger();
|
||||
@@ -0,0 +1,91 @@
|
||||
import { sep, basename } from 'path';
|
||||
import { PathDiscovery } from '../services/path-discovery.js';
|
||||
|
||||
/**
|
||||
* PathResolver utility for managing claude-mem file system paths
|
||||
* Now delegates to PathDiscovery service for centralized path management
|
||||
*/
|
||||
export class PathResolver {
|
||||
private pathDiscovery: PathDiscovery;
|
||||
|
||||
// <Block> 1.1 ====================================
|
||||
constructor() {
|
||||
this.pathDiscovery = PathDiscovery.getInstance();
|
||||
}
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 1.2 ====================================
|
||||
getConfigDir(): string {
|
||||
return this.pathDiscovery.getDataDirectory();
|
||||
}
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 1.3 ====================================
|
||||
getIndexDir(): string {
|
||||
return this.pathDiscovery.getIndexDirectory();
|
||||
}
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 1.4 ====================================
|
||||
getIndexPath(): string {
|
||||
return this.pathDiscovery.getIndexPath();
|
||||
}
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 1.5 ====================================
|
||||
getArchiveDir(): string {
|
||||
return this.pathDiscovery.getArchivesDirectory();
|
||||
}
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 1.6 ====================================
|
||||
getProjectArchiveDir(projectName: string): string {
|
||||
return this.pathDiscovery.getProjectArchiveDirectory(projectName);
|
||||
}
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 1.7 ====================================
|
||||
getLogsDir(): string {
|
||||
return this.pathDiscovery.getLogsDirectory();
|
||||
}
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 1.8 ====================================
|
||||
static ensureDirectory(dirPath: string): void {
|
||||
PathDiscovery.getInstance().ensureDirectory(dirPath);
|
||||
}
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 1.9 ====================================
|
||||
static ensureDirectories(dirPaths: string[]): void {
|
||||
PathDiscovery.getInstance().ensureDirectories(dirPaths);
|
||||
}
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 1.10 ===================================
|
||||
static extractProjectName(transcriptPath: string): string {
|
||||
return PathDiscovery.extractProjectName(transcriptPath);
|
||||
}
|
||||
|
||||
// <Block> 1.11 ===================================
|
||||
/**
|
||||
* DRY utility function: Canonical source for getting the current project prefix
|
||||
* Replaces all instances of path.basename(process.cwd()) across the codebase
|
||||
* @returns The current project directory name, sanitized for use as a prefix
|
||||
*/
|
||||
static getCurrentProjectPrefix(): string {
|
||||
return PathDiscovery.getCurrentProjectName();
|
||||
}
|
||||
// </Block> =======================================
|
||||
|
||||
// <Block> 1.12 ===================================
|
||||
/**
|
||||
* DRY utility function: Gets raw project name without sanitization
|
||||
* For use in contexts where original directory name is needed (e.g., display)
|
||||
* @returns The current project directory name as-is
|
||||
*/
|
||||
static getCurrentProjectName(): string {
|
||||
return PathDiscovery.getCurrentProjectName();
|
||||
}
|
||||
// </Block> =======================================
|
||||
}
|
||||
@@ -0,0 +1,98 @@
|
||||
import { readFileSync, existsSync } from 'fs';
|
||||
import { join } from 'path';
|
||||
import { PathResolver } from './paths.js';
|
||||
import type { Settings } from './types.js';
|
||||
|
||||
/**
|
||||
* Settings utilities for managing ~/.claude-mem/settings.json
|
||||
*/
|
||||
export class SettingsManager {
|
||||
private static settingsPath: string;
|
||||
private static cachedSettings: Settings | null = null;
|
||||
|
||||
static {
|
||||
const pathResolver = new PathResolver();
|
||||
this.settingsPath = join(pathResolver.getConfigDir(), 'settings.json');
|
||||
}
|
||||
|
||||
/**
|
||||
* Safely read settings.json with error handling
|
||||
* Returns empty object if file doesn't exist or is malformed
|
||||
*/
|
||||
static readSettings(): Settings {
|
||||
// Return cached settings if available
|
||||
if (this.cachedSettings !== null) {
|
||||
return this.cachedSettings;
|
||||
}
|
||||
|
||||
try {
|
||||
if (existsSync(this.settingsPath)) {
|
||||
const content = readFileSync(this.settingsPath, 'utf-8');
|
||||
const settings = JSON.parse(content) as Settings;
|
||||
this.cachedSettings = settings;
|
||||
return settings;
|
||||
}
|
||||
} catch {
|
||||
// File is malformed or unreadable - return empty settings
|
||||
}
|
||||
|
||||
// File doesn't exist or failed to read
|
||||
const emptySettings: Settings = {};
|
||||
this.cachedSettings = emptySettings;
|
||||
return emptySettings;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a specific setting value with optional fallback
|
||||
*/
|
||||
static getSetting<K extends keyof Settings>(
|
||||
key: K,
|
||||
fallback?: Settings[K]
|
||||
): Settings[K] | undefined {
|
||||
const settings = this.readSettings();
|
||||
return settings[key] ?? fallback;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the Claude binary path from settings
|
||||
* Falls back to 'claude' if not found or settings don't exist
|
||||
*/
|
||||
static getClaudePath(): string {
|
||||
const claudePath = this.getSetting('claudePath', 'claude');
|
||||
return claudePath as string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Clear cached settings (useful for testing or after settings changes)
|
||||
*/
|
||||
static clearCache(): void {
|
||||
this.cachedSettings = null;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Convenience function to get Claude binary path
|
||||
* Can be imported directly for simple use cases
|
||||
*/
|
||||
export function getClaudePath(): string {
|
||||
return SettingsManager.getClaudePath();
|
||||
}
|
||||
|
||||
/**
|
||||
* Convenience function to read all settings
|
||||
* Can be imported directly for simple use cases
|
||||
*/
|
||||
export function readSettings(): Settings {
|
||||
return SettingsManager.readSettings();
|
||||
}
|
||||
|
||||
/**
|
||||
* Convenience function to get a specific setting
|
||||
* Can be imported directly for simple use cases
|
||||
*/
|
||||
export function getSetting<K extends keyof Settings>(
|
||||
key: K,
|
||||
fallback?: Settings[K]
|
||||
): Settings[K] | undefined {
|
||||
return SettingsManager.getSetting(key, fallback);
|
||||
}
|
||||
@@ -0,0 +1,263 @@
|
||||
export interface HookPayload {
|
||||
session_id: string;
|
||||
transcript_path: string;
|
||||
hook_event_name: string;
|
||||
}
|
||||
|
||||
export interface PreCompactPayload extends HookPayload {
|
||||
hook_event_name: 'PreCompact';
|
||||
trigger: 'manual' | 'auto';
|
||||
custom_instructions?: string;
|
||||
}
|
||||
|
||||
export interface SessionStartPayload extends HookPayload {
|
||||
hook_event_name: 'SessionStart';
|
||||
source: 'startup' | 'compact' | 'vscode' | 'web';
|
||||
}
|
||||
|
||||
export interface UserPromptSubmitPayload extends HookPayload {
|
||||
hook_event_name: 'UserPromptSubmit';
|
||||
prompt: string;
|
||||
cwd: string;
|
||||
}
|
||||
|
||||
export interface PreToolUsePayload extends HookPayload {
|
||||
hook_event_name: 'PreToolUse';
|
||||
tool_name: string;
|
||||
tool_input: Record<string, unknown>;
|
||||
}
|
||||
|
||||
export interface PostToolUsePayload extends HookPayload {
|
||||
hook_event_name: 'PostToolUse';
|
||||
tool_name: string;
|
||||
tool_input: Record<string, unknown>;
|
||||
tool_response: Record<string, unknown> & {
|
||||
success?: boolean;
|
||||
};
|
||||
}
|
||||
|
||||
export interface NotificationPayload extends HookPayload {
|
||||
hook_event_name: 'Notification';
|
||||
message: string;
|
||||
title?: string;
|
||||
}
|
||||
|
||||
export interface StopPayload extends HookPayload {
|
||||
hook_event_name: 'Stop';
|
||||
stop_hook_active: boolean;
|
||||
}
|
||||
|
||||
export interface BaseHookResponse {
|
||||
continue?: boolean;
|
||||
stopReason?: string;
|
||||
suppressOutput?: boolean;
|
||||
}
|
||||
|
||||
export interface PreCompactResponse extends BaseHookResponse {
|
||||
decision?: 'approve' | 'block';
|
||||
reason?: string;
|
||||
}
|
||||
|
||||
export interface SessionStartResponse extends BaseHookResponse {
|
||||
hookSpecificOutput?: {
|
||||
hookEventName: 'SessionStart';
|
||||
additionalContext?: string;
|
||||
};
|
||||
}
|
||||
|
||||
export interface PreToolUseResponse extends BaseHookResponse {
|
||||
permissionDecision?: 'allow' | 'deny' | 'ask';
|
||||
permissionDecisionReason?: string;
|
||||
}
|
||||
|
||||
export interface CompressionResult {
|
||||
compressedLines: string[];
|
||||
originalTokens: number;
|
||||
compressedTokens: number;
|
||||
compressionRatio: number;
|
||||
memoryNodes: string[];
|
||||
}
|
||||
|
||||
export interface MemoryNode {
|
||||
id: string;
|
||||
type: 'document';
|
||||
content: string;
|
||||
timestamp: string;
|
||||
metadata?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
export class HookError extends Error {
|
||||
constructor(
|
||||
message: string,
|
||||
public hookType: string,
|
||||
public payload?: HookPayload,
|
||||
public code?: string
|
||||
) {
|
||||
super(message);
|
||||
this.name = 'HookError';
|
||||
}
|
||||
}
|
||||
|
||||
export class CompressionError extends Error {
|
||||
constructor(
|
||||
message: string,
|
||||
public transcriptPath: string,
|
||||
public stage: 'reading' | 'analyzing' | 'compressing' | 'writing'
|
||||
) {
|
||||
super(message);
|
||||
this.name = 'CompressionError';
|
||||
}
|
||||
}
|
||||
|
||||
export interface Logger {
|
||||
info(message: string, meta?: Record<string, unknown>): void;
|
||||
warn(message: string, meta?: Record<string, unknown>): void;
|
||||
error(message: string, error?: Error, meta?: Record<string, unknown>): void;
|
||||
debug(message: string, meta?: Record<string, unknown>): void;
|
||||
}
|
||||
|
||||
export class FileLogger implements Logger {
|
||||
constructor(
|
||||
private logFile: string,
|
||||
private enableDebug = false
|
||||
) {}
|
||||
|
||||
info(message: string, meta?: Record<string, unknown>): void {
|
||||
this.log('INFO', message, meta);
|
||||
}
|
||||
|
||||
warn(message: string, meta?: Record<string, unknown>): void {
|
||||
this.log('WARN', message, meta);
|
||||
}
|
||||
|
||||
error(message: string, error?: Error, meta?: Record<string, unknown>): void {
|
||||
const errorMeta = error ? { error: error.message, stack: error.stack } : {};
|
||||
this.log('ERROR', message, { ...meta, ...errorMeta });
|
||||
}
|
||||
|
||||
debug(message: string, meta?: Record<string, unknown>): void {
|
||||
if (this.enableDebug) {
|
||||
this.log('DEBUG', message, meta);
|
||||
}
|
||||
}
|
||||
|
||||
private log(
|
||||
level: string,
|
||||
message: string,
|
||||
meta?: Record<string, unknown>
|
||||
): void {
|
||||
const timestamp = new Date().toISOString();
|
||||
const metaStr = meta ? ` ${JSON.stringify(meta)}` : '';
|
||||
const logLine = `[${timestamp}] ${level}: ${message}${metaStr}\n`;
|
||||
|
||||
console.error(logLine);
|
||||
}
|
||||
}
|
||||
|
||||
export function validateHookPayload(
|
||||
payload: unknown,
|
||||
expectedType: string
|
||||
): HookPayload {
|
||||
if (!payload || typeof payload !== 'object') {
|
||||
throw new HookError(
|
||||
`Invalid payload: expected object, got ${typeof payload}`,
|
||||
expectedType
|
||||
);
|
||||
}
|
||||
|
||||
const hookPayload = payload as Record<string, unknown>;
|
||||
|
||||
if (!hookPayload.session_id || typeof hookPayload.session_id !== 'string') {
|
||||
throw new HookError(
|
||||
'Missing or invalid session_id',
|
||||
expectedType,
|
||||
hookPayload as unknown as HookPayload
|
||||
);
|
||||
}
|
||||
|
||||
if (
|
||||
!hookPayload.transcript_path ||
|
||||
typeof hookPayload.transcript_path !== 'string'
|
||||
) {
|
||||
throw new HookError(
|
||||
'Missing or invalid transcript_path',
|
||||
expectedType,
|
||||
hookPayload as unknown as HookPayload
|
||||
);
|
||||
}
|
||||
|
||||
return hookPayload as unknown as HookPayload;
|
||||
}
|
||||
|
||||
export function createSuccessResponse(
|
||||
additionalData?: Record<string, unknown>
|
||||
): BaseHookResponse {
|
||||
return {
|
||||
continue: true,
|
||||
...additionalData,
|
||||
};
|
||||
}
|
||||
|
||||
export function createErrorResponse(
|
||||
reason: string,
|
||||
additionalData?: Record<string, unknown>
|
||||
): BaseHookResponse {
|
||||
return {
|
||||
continue: false,
|
||||
stopReason: reason,
|
||||
...additionalData,
|
||||
};
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// SETTINGS AND CONFIGURATION TYPES
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Main settings interface for claude-mem configuration
|
||||
*/
|
||||
export interface Settings {
|
||||
autoCompress?: boolean;
|
||||
projectName?: string;
|
||||
installed?: boolean;
|
||||
backend?: string;
|
||||
embedded?: boolean;
|
||||
saveMemoriesOnClear?: boolean;
|
||||
claudePath?: string;
|
||||
[key: string]: unknown; // Allow additional properties
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// MCP CLIENT INTERFACE TYPES
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Document structure for MCP operations
|
||||
*/
|
||||
export interface MCPDocument {
|
||||
id: string;
|
||||
content: string;
|
||||
metadata?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Search result structure from MCP operations
|
||||
*/
|
||||
export interface MCPSearchResult {
|
||||
documents?: MCPDocument[];
|
||||
ids?: string[];
|
||||
metadatas?: Record<string, unknown>[];
|
||||
distances?: number[];
|
||||
[key: string]: unknown;
|
||||
}
|
||||
|
||||
/**
|
||||
* Interface for MCP client implementations (Chroma-based)
|
||||
*/
|
||||
export interface IMCPClient {
|
||||
connect(): Promise<void>;
|
||||
disconnect(): Promise<void>;
|
||||
addDocuments(documents: MCPDocument[]): Promise<void>;
|
||||
queryDocuments(query: string, limit?: number): Promise<MCPSearchResult>;
|
||||
getDocuments(ids?: string[]): Promise<MCPSearchResult>;
|
||||
}
|
||||
Reference in New Issue
Block a user