Shristi

Persistent AI Memory for Every Repository

Shristi is an offline-first, production-quality command-line interface (CLI) tool designed to generate and maintain persistent, deterministic project memory for AI assistants. It scans your repository, runs localized tech stack analyzers, generates developer context, and indexes project memories into a local vector database. By outputting highly optimized, token-efficient blocks of context, Shristi provides any Large Language Model (LLM) with immediate, deep familiarity with your codebase.

Why Shristi?

• Context Fragmentation: AI assistants forget codebase details as conversations progress. Context windows are limited, and copying-pasting files manually is tedious.
• Outdated Project Summaries: Readmes and code comments go out of date quickly. Developers waste time repeatedly explaining architecture, database schemas, and folder structures.
• API and Network Limits: Sending entire repositories to remote LLMs is expensive, slow, and raises data privacy concerns.
• The Solution: Shristi creates a local, git-aware, structured knowledge index (.shristi/) directly in your workspace. It computes incremental changes on every commit, updates code summaries, and uses local vector search (RAG) to inject only the most relevant codebase memory into your prompt.

Features

• Persistent Project Memory: Generates a unified, structured summary of your codebase (PROJECT_MEMORY.md) and a combined prompt context (context.md).
• Incremental Learning: Computes the delta between git commits to analyze files within the modified blast-radius, instantly updating memory.
• Git-Aware Hooks: Automatically triggers learning cycles in the background on post-commit hooks.
• Local SQLite Vector Store: Houses semantic embeddings in a local SQLite vector database (vectors.db) for offline querying.
• Offline Semantic Search: Cosine similarity over local embeddings using ONNX-optimized embedding models without any external API calls.
• Context Generation (RAG): Consolidates memories into token-efficient context blocks dynamically filtered using queries.
• Multi-Language Analysis: Automatically detects and parses configuration files, READMEs, scripts, and build environments.
• Deterministic and Configurable: Custom exclusions, folder boundaries, and settings are fully controlled via config.json.

Installation

Ensure Node.js version 22.x or above is installed:

npm install -g shristi-cli

Quick Start

Get Shristi running in your repository in four steps:

1. Initialize Shristi:

   shristi init

   Creates the .shristi directory with default ignore patterns and configuration.

2. Index and Learn Codebase:

   shristi learn

   Scans repository files, runs technology stack analyzers, and populates the local vector database.

3. Generate Consolidated Context:

   shristi context

   Outputs the consolidated, token-efficient prompt context ready to be fed to an AI.

4. Semantically Search Memories:

   shristi search "database connection pool"

   Queries the local vector database to find the most relevant chunks using cosine similarity.

Typical Workflow

Repository
    │
    ▼
shristi init (Creates configuration and structure)
    │
    ▼
shristi learn (Full scan & initial vectorization)
    │
    ▼
[Develop & Commit Changes]
    │
    ▼
Git Hook Triggers (Automatic background learning run)
    │
    ▼
shristi context (Generates updated token-efficient AI prompt)

Commands

shristi init

• Purpose: Initializes the .shristi/ directory, writes starter config, and registers the post-commit git hook.
• Syntax: shristi init [options]
• Options:
  • -f, --force Force reinitialization and overwrite existing configuration.
  • -d, --debug Enable verbose debug logging and stack traces.
• Example: shristi init
• Expected Output:

  ✔ Initialized Shristi project memory directory at /path/to/project/.shristi
  ✔ Automatically installed post-commit Git hook.

shristi learn

• Purpose: Scans project files, processes stack analyzers, updates memory.json, and indexes files in the vector store.
• Syntax: shristi learn [options]
• Options:
  • -f, --force Force a full scanned refresh of memory.
  • --repair Rebuild vector index from scratch.
  • --silent Run execution silently in the background.
  • --no-gitignore Skip matching .gitignore rules.
• Example: shristi learn --repair
• Expected Output:

  - Shristi is updating project memory...
  ✔ Successfully learned changes (full scan, 12 files).
  ✔ Documentation and context regenerated at /path/to/project/.shristi

shristi context

• Purpose: Consolidates persistent codebase memory into an optimized prompt block. If a query is provided, uses semantic search to generate relevant context.
• Syntax: shristi context [query] [options]
• Options:
  • -r, --raw Omit debug header and formatting statistics.
• Example: shristi context "JWT authentication"
• Expected Output: An LLM-ready markdown block containing project summaries, matched files, and developer notes.

shristi search

• Purpose: Performs a local semantic search over indexed repository chunks.
• Syntax: shristi search <query> [options]
• Options:
  • --top <number> Number of top results to return (defaults to 5).
• Example: shristi search "error handling"
• Expected Output:

  Top Semantic Matches:
  1. error.ts (Score: 0.89)
     - Standardized error classes and validation schemas...

shristi status

• Purpose: Displays Git hook status, lock files, and repository statistics.
• Syntax: shristi status
• Example: shristi status
• Expected Output: Details on the last processed commit, hook health, and file indexing percentages.

shristi history

• Purpose: Displays commit history processing logs and version metrics.
• Syntax: shristi history
• Example: shristi history
• Expected Output: List of recent commits processed by Shristi.

shristi hook

• Purpose: Installs or removes the post-commit git hook manually.
• Syntax: shristi hook <install | remove>
• Example: shristi hook remove

How It Works

Repository Files ──► File Scanner (Respecting ignore patterns)
                          │
                          ▼
                  Stack Analyzers (Extract metadata from package.json, Dockerfile, etc.)
                          │
                          ▼
                  Memory Engine (Generates memory.json & PROJECT_MEMORY.md)
                          │
                          ▼
               Local Embeddings Pipeline (Local ONNX Transformers Model)
                          │
                          ▼
                SQLite Vector Store (Persists vectors to vectors.db)
                          │
                          ▼
            Semantic Retrieval / Context (Outputs prompt context for LLMs)

Generated Project Structure

Upon running shristi init and shristi learn, a .shristi/ folder is generated in your project root:

| File / Folder | Purpose | | :--- | :--- | | config.json | Project-specific scanner rules, auto-updates, and ignore patterns. | | version.json | Tracking metadata version and migration history. | | history.json | Stores log records of recently analyzed commits. | | memory.json | Consolidated JSON data parsed from your codebase. | | PROJECT_MEMORY.md | Read-only structural summary of technology stack and codebase. | | context.md | The final consolidated context ready to copy-paste to your LLM. | | custom_notes.md | Persistent file where you write developer notes. Never overwritten by Shristi. | | vectors.db | Local SQLite database containing chunked text embeddings. | | logs/ | Command execution logs for diagnostics. | | .lock | Lock file preventing concurrent executions in background hooks. |

Supported Technologies

Shristi automatically inspects and analyzes the following ecosystems and file formats:

| Category | Supported Assets | | :--- | :--- | | Languages | TypeScript, JavaScript, Java, Python | | Package Managers | npm (package.json), Maven (pom.xml), Gradle (build.gradle), pip (requirements.txt) | | Infrastructure | Docker (Dockerfile) | | Version Control | Git | | Documentation | Markdown (README.md, custom_notes.md) |

Architecture

Shristi is designed as a modern, decoupled monorepo composed of three main layers:

• CLI (shristi-cli): Handles user interactions, parses CLI inputs, displays spinners, and logs results.
• Core (@shristi/core): Contains the core domain logic, scanners, AST stack analyzers, git service, memory engine, embedding generators, and SQLite vector storage.
• Shared (@shristi/shared): Declares configuration schemas, standardized error hierarchies, and shared constants.

Philosophy

• Offline-First: No API keys, external SaaS dependecies, or active network connections are required during runtime. Everything runs locally.
• Deterministic: Given the same repository state, Shristi generates identical memory blocks to avoid git diff noise.
• Local Storage: Your codebase context and metadata never leave your local machine.
• Fast: Executes incremental runs in milliseconds by analyzing only changed files.

Roadmap

• [x] Local vector store with SQLite integration
• [x] Local semantic search and RAG capabilities
• [x] Incremental repository learning
• [x] Autonomous post-commit Git hooks
• [ ] Multi-vector search boosting for specific folders
• [ ] Integration with IDE plugins (VS Code / JetBrains)

Contributing

We welcome community contributions. To set up the workspace locally:

1. Clone the repository.
2. Run npm install to install dependencies and establish workspace links.
3. Use npm run build to compile the TypeScript workspaces.
4. Run npm run test to verify unit and integration tests.

License

MIT License. Copyright (c) 2026 Subrato Kundu.