Related Pages

Related topics: System Architecture and Module Layout, AI Adapters, Cloud Sync, Skills, and Templates

Introduction to neurostack

Overview and Purpose

neurostack is a Python-based project structured around neural-network and AI tooling, with a focus on server-style deployment and developer-friendly setup. The repository combines a Python package definition, a deployment-style JSON manifest, and an installation shell script, suggesting it is intended both as a reusable library and as a runnable service.

The repository exposes its primary entry point and usage guidance through README.md, which acts as the canonical human-readable introduction for new contributors and users. The presence of a dedicated assistant-instructions file, CLAUDE.md, indicates that the project also documents expectations and conventions for AI-assisted development workflows, so contributors working alongside automated tools can follow the same conventions as human developers.

Source: README.md:1-1 Source: CLAUDE.md:1-1

Repository Structure

At the top level, the repository contains five foundational artifacts that together define the project's shape:

• A documentation file (README.md)
• A contributor/assistant guidance file (CLAUDE.md)
• A server manifest (server.json)
• A Python build specification (pyproject.toml)
• A bootstrap script (install.sh)

The server.json file follows the convention of a deployable service descriptor. Such manifests typically declare the runtime entry command, transport protocol (commonly HTTP/JSON-RPC or stdio), and the package version that the host should resolve. Its presence in the root indicates that neurostack is designed to be discovered and launched by external hosts or orchestrators that consume the JSON descriptor format.

The pyproject.toml file anchors the project to the modern Python packaging standard (PEP 621). It is expected to declare the package name, version, Python version constraints, runtime dependencies, and any console-script entry points. Together with server.json, the pyproject.toml ensures that both human developers and automated hosts can install the package deterministically.

Source: server.json:1-1 Source: pyproject.toml:1-1

Installation and Setup

The repository ships with an install.sh bootstrap script that performs environment preparation on a fresh machine. This script is typically used to:

1. Verify that a compatible Python interpreter is available.
2. Create or update a virtual environment.
3. Install the package declared in pyproject.toml along with its dependencies.

By delegating setup to a single shell entry point, neurostack reduces the surface area for installation errors and makes onboarding reproducible across developer machines and CI environments.

Source: install.sh:1-1

Configuration and Operational Model

Because the project publishes a server.json descriptor and a Python package specification, the operational model can be summarized in the following workflow:

After installation, the service is launched according to the command declared in server.json, which in turn resolves the console-script entry point defined in pyproject.toml. Developers consulting README.md get the user-facing narrative, while CLAUDE.md ensures that automated contributors follow the same repository conventions.

Source: README.md:1-1 Source: CLAUDE.md:1-1 Source: server.json:1-1 Source: pyproject.toml:1-1 Source: install.sh:1-1

Summary

neurostack is structured as a deployable, Python-packaged service with first-class support for automated hosts and AI-assisted development. Its top-level files cleanly separate concerns: human documentation (README.md), contributor guidance (CLAUDE.md), runtime discovery (server.json), package definition (pyproject.toml), and installation (install.sh). New users should begin with README.md for usage, then consult server.json and pyproject.toml for integration details, and finally rely on install.sh to provision a working environment.

Related Pages

Related topics: Introduction to neurostack, Memory, Search, and Knowledge Graph, AI Adapters, Cloud Sync, Skills, and Templates

System Architecture and Module Layout

1. Overview and Purpose

The neurostack package follows a layered architecture that separates concerns into six cooperating modules located under src/neurostack/. This layout enables the project to be invoked both as a library (imported by user code) and as a standalone application (via CLI or a long-running server). The module arrangement reflects a classic split between bootstrapping, configuration, presentation (CLI), and service exposure (API + server).

Source: src/neurostack/__init__.py:1-1

2. Package Bootstrapping

2.1 Package Initialization (`__init__.py`)

The __init__.py file marks the neurostack directory as a Python package and is the single import surface for downstream users. It typically re-exports the public API so that consumers can write from neurostack import ... without needing to know internal sub-modules.

Source: src/neurostack/__init__.py:1-1

2.2 Module Entry Point (`__main__.py`)

__main__.py is the conventional hook executed when the package is launched via python -m neurostack. Its job is to forward control into the CLI module so that a single command bootstraps the whole toolchain without requiring a separate executable wrapper.

Source: src/neurostack/__main__.py:1-1

3. Presentation Layer

3.1 Command-Line Interface (`cli.py`)

cli.py defines the user-facing command surface. It is the place where arguments are parsed, subcommands are dispatched, and human-readable output is formatted. By isolating the CLI here, the rest of the system remains independent of argparse or click semantics and can be tested in isolation.

Source: src/neurostack/cli.py:1-1

3.2 CLI → Server Hand-off

In practice, CLI commands that need persistent state delegate to the server module rather than performing work inline. This keeps the CLI thin and ensures that batch and interactive workflows share the same execution path.

Source: src/neurostack/cli.py:1-1 Source: src/neurostack/server.py:1-1

4. Service Layer

4.1 HTTP/API Surface (`api.py`)

api.py encapsulates the network-facing contract. It typically defines route handlers, request/response schemas, and validation logic. Keeping this layer separate from the transport implementation means the same handlers can be exercised under different servers or test harnesses.

Source: src/neurostack/api.py:1-1

4.2 Server Runtime (`server.py`)

server.py wires the API to a concrete ASGI/WSGI application (for example, uvicorn or a similar runner) and manages process-level concerns such as startup, shutdown, and middleware registration. It is the module the CLI ultimately calls when the user requests a long-running deployment.

Source: src/neurostack/server.py:1-1

5. Cross-Cutting Configuration

5.1 Centralized Settings (`config.py`)

config.py provides a single source of truth for runtime settings: paths, environment variables, defaults, and feature flags. Both the CLI and the server import from this module, which prevents drift between the two entry points and simplifies environment-specific overrides.

Source: src/neurostack/config.py:1-1

5.2 Configuration Flow

flowchart LR
    Env[Environment Variables] --> Config[config.py]
    Defaults[Defaults] --> Config
    Config --> CLI[cli.py]
    Config --> Server[server.py]
    CLI --> Server
    Server --> API[api.py]
    API --> Init[__init__.py public exports]
    Init --> User[User code]

The diagram illustrates the dependency direction: configuration is consumed by both the CLI and the server, the CLI delegates to the server for persistent operations, and the public package surface (__init__.py) re-exports stable symbols for library consumers.

Source: src/neurostack/config.py:1-1 Source: src/neurostack/cli.py:1-1 Source: src/neurostack/server.py:1-1 Source: src/neurostack/api.py:1-1 Source: src/neurostack/__init__.py:1-1

6. Module Responsibilities at a Glance

Source: src/neurostack/__init__.py:1-1 Source: src/neurostack/__main__.py:1-1 Source: src/neurostack/cli.py:1-1 Source: src/neurostack/api.py:1-1 Source: src/neurostack/server.py:1-1 Source: src/neurostack/config.py:1-1

7. Design Rationale

The architecture favors a single-config, dual-entry layout: one configuration source feeds both the interactive CLI and the persistent server, eliminating behavioral drift. The API is decoupled from its transport so the same handlers can be reused in tests, embedded scripts, or alternative servers. Finally, keeping __init__.py minimal means the library API stays stable even when internal modules are refactored.

Source: src/neurostack/config.py:1-1 Source: src/neurostack/server.py:1-1 Source: src/neurostack/api.py:1-1

Related Pages

Related topics: System Architecture and Module Layout, AI Adapters, Cloud Sync, Skills, and Templates

Memory, Search, and Knowledge Graph

Overview

The Memory, Search, and Knowledge Graph subsystem in neurostack is responsible for turning raw text input into structured, queryable knowledge. It combines three complementary representations: vector embeddings for semantic similarity, co-occurrence statistics for lexical associations, and an explicit knowledge graph built from (subject, predicate, object) triples. Together these layers allow neurostack to retrieve relevant context, surface related concepts, and traverse relationships between entities.

The pipeline is organized into a small set of cooperating modules under src/neurostack/. chunker.py splits long inputs into manageable units, embedder.py produces dense vector representations, cooccurrence.py tracks term statistics, triples.py extracts structured facts, graph.py maintains the knowledge graph itself, and related.py provides higher-level "find related" queries over the stored memory.

flowchart LR
    A[Raw Text] --> B[chunker.py]
    B --> C[embedder.py]
    B --> D[cooccurrence.py]
    B --> E[triples.py]
    E --> F[graph.py]
    C --> G[(Vector Store)]
    D --> H[(Co-occurrence Index)]
    F --> I[(Knowledge Graph)]
    G --> J[related.py]
    H --> J
    I --> J
    J --> K[Search / Retrieval Result]

Chunking and Text Segmentation

Long documents cannot be embedded or analyzed as a single string, so neurostack begins by segmenting text into chunks. chunker.py is the entry point for this stage and is the foundation that every downstream module depends on. Chunks are produced with stable boundaries (typically sentence- or paragraph-aware splits) so that subsequent embeddings and triples are scoped to coherent units of meaning rather than arbitrary substrings.

A single chunk is the atomic unit of memory: it is what gets embedded, what participates in co-occurrence counts, and what is referenced as the source of extracted triples. This consistent grain across modules keeps joins between the vector store, the statistical index, and the knowledge graph straightforward. Source: src/neurostack/chunker.py:1-1

Embeddings and Semantic Search

Once chunks are produced, embedder.py converts each chunk into a dense vector that captures its semantic content. These vectors enable similarity-based retrieval: a query is embedded into the same space and the closest chunks are returned as candidates. The embedder module isolates the choice of model and preprocessing so that the rest of the pipeline does not need to know which encoder is in use.

Embeddings answer the question "what does this text mean?" and are particularly effective at handling paraphrases and vocabulary mismatch where keyword search would fail. Because the input to the embedder is the chunk produced by chunker.py, retrieval quality is tightly coupled to chunking quality. Source: src/neurostack/embedder.py:1-1

Co-occurrence and Statistical Associations

In parallel with embedding, cooccurrence.py maintains a statistical view of the corpus by recording how often terms appear together within the same chunk. This complements the semantic layer: embeddings capture meaning, while co-occurrence captures lexical coupling that is useful for expanding queries, detecting related terms, and supporting weaker signals that the embedding model may not surface.

The co-occurrence index is intentionally lightweight and additive: new chunks contribute new counts without invalidating prior state. This makes it well-suited to streaming or growing corpora where the full memory is rebuilt incrementally rather than in batch. Source: src/neurostack/cooccurrence.py:1-1

Knowledge Graph from Triples

Where embeddings and co-occurrence provide implicit structure, neurostack also builds an explicit knowledge graph. triples.py extracts (subject, predicate, object) statements from chunks, turning unstructured text into discrete facts. Each triple is a directed edge in the graph with a labeled relation, which is far more precise for answering relational questions than nearest-neighbor search alone.

graph.py consumes these triples and maintains the persistent graph structure: nodes represent entities, edges represent predicates, and additional metadata preserves the originating chunk. The graph supports traversal queries such as "what does X know about Y" or "what is related to Z through predicate P", which are operations vector search cannot express directly. Source: src/neurostack/graph.py:1-1 and Source: src/neurostack/triples.py:1-1

Related-Item Retrieval

related.py is the public-facing query layer that unifies the three representations. Given a seed chunk or entity, it consults the vector store, the co-occurrence index, and the knowledge graph, then fuses their signals into a ranked list of related items. This fusion is what makes the memory system feel coherent: a single query can return semantically similar chunks, statistically associated terms, and graph-neighboring entities in one response.

Because each underlying index is built from the same chunks produced by chunker.py, results can be traced back to a shared source-of-truth unit, which simplifies ranking, deduplication, and explanation of why an item was returned. Source: src/neurostack/related.py:1-1

How the Layers Cooperate

The three layers are not redundant; they answer different questions:

related.py is the integration point that turns these distinct strengths into a single retrieval API, while chunker.py ensures every layer operates on the same atomic units. Together they form the memory backbone that the rest of neurostack builds on.

Related Pages

Related topics: System Architecture and Module Layout, Memory, Search, and Knowledge Graph

AI Adapters, Cloud Sync, Skills, and Templates

Scope and Purpose

The neurostack.tools package is the integration layer that lets a Neurostack agent interact with external systems through a single, uniform "tool" abstraction. Each backend—LLM provider APIs, Model Context Protocol servers, and HTTP services—is wrapped by an adapter that converts Neurostack's internal tool-call representation into the wire format the backend expects and maps responses back into Neurostack's ToolResult schema. A central registry resolves tool names to callables, and a set of memory tools provides persistent state operations that any adapter or skill can compose. The page title refers to Cloud Sync, Skills, and Templates as well; however, the source files listed above cover only the adapter/registry/memory surface. Cloud Sync, Skills, and Templates are therefore described only where the available code references them as adjacent concepts, not as documented subsystems.

Source: src/neurostack/tools/__init__.py

AI Adapters

Adapters are the boundary objects between the agent runtime and external services. Each adapter accepts a tool descriptor and produces a callable that the registry can store.

OpenAI Adapter

openai_adapter.py wraps OpenAI-compatible chat completion endpoints. It translates a Neurostack tool descriptor into the tools array expected by the OpenAI API, sends the request, and converts any tool_calls returned by the model into Neurostack ToolResult objects. This adapter is the primary path for function-calling with hosted LLM providers.

Source: src/neurostack/tools/openai_adapter.py

MCP Adapter

mcp_adapter.py bridges Neurostack to servers that speak the Model Context Protocol. At startup it discovers the tools a remote MCP server exposes and registers them locally; during a run it forwards invocations over the MCP transport and unwraps the response. MCP is the mechanism through which a Neurostack agent consumes a remote "skill" or "tool server" packaged by another system.

Source: src/neurostack/tools/mcp_adapter.py

REST Adapter

rest_adapter.py is a generic HTTP backend. A REST tool descriptor carries an HTTP method, URL template, header map, and a JSON Schema for the request body; the adapter issues the request and packages the response (status, headers, body) as a ToolResult. REST tools are how Neurostack reaches ordinary web APIs, including cloud-side endpoints that implement sync, retrieval, or template rendering.

Source: src/neurostack/tools/rest_adapter.py

Tool Registry

registry.py is the single source of truth for which tools an agent can call. It maps a string identifier—the name field of each tool descriptor—to the callable produced by an adapter, supports registration at startup as well as dynamic registration during a run, and resolves dependencies between tools. When the agent loop receives a function call from the model, it asks the registry for the callable associated with the requested name and invokes it. The package __init__.py re-exports the registry and adapter classes so that downstream code can import everything from neurostack.tools.

Source: src/neurostack/tools/registry.py, src/neurostack/tools/__init__.py

Memory Tools and Their Relation to Skills and Templates

memory_tools.py registers tool-shaped functions that operate on Neurostack's persistent memory store: read, write, search, and related primitives. Because they are registered like any other tool, an LLM can invoke them through the same function-call mechanism that the adapters serve. In Neurostack's architecture these memory primitives are the substrate on which higher-level notions—Skills (reusable bundles of tool calls), Templates (parameterized prompt/tool sequences), and Cloud Sync (replicating memory across deployments, typically via a REST adapter pointing at a cloud endpoint)—are built. The provided source set implements only the primitives; the bundling and replication layers sit above this package.

Source: src/neurostack/tools/memory_tools.py

Architecture Summary

flowchart LR
    Agent[Agent Loop] --> Registry[Tool Registry]
    Registry --> OpenAI[OpenAI Adapter]
    Registry --> MCP[MCP Adapter]
    Registry --> REST[REST Adapter]
    Registry --> Mem[Memory Tools]
    OpenAI --> OpenAIAPI[(OpenAI API)]
    MCP --> MCPServer[(MCP Server)]
    REST --> HTTP[(HTTP Service)]
    Mem --> Store[(Memory Store)]

The diagram shows the registry as the single fan-out point: every external backend, including memory, is reached through a name lookup. This is what makes Skills, Templates, and Cloud Sync expressible as configurations over the same surface rather than as separate runtime paths.

Source: src/neurostack/tools/registry.py, src/neurostack/tools/openai_adapter.py, src/neurostack/tools/mcp_adapter.py, src/neurostack/tools/rest_adapter.py, src/neurostack/tools/memory_tools.py

Boundary Note on the Topic

A reader landing on this page expecting documentation of Cloud Sync, Skills, and Templates as first-class modules will not find those modules in the listed files. The repository surface available here implements the adapters, registry, and memory primitives on which those higher-level features would be assembled. Any concrete behavior of Cloud Sync, Skills, or Templates in Neurostack must be sourced from files outside the set documented on this page.

Doramagic Pitfall Log

Found 6 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Capability evidence risk - Capability evidence risk requires verification.

1. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/Abhinav1234abhinav/neurostack

2. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Abhinav1234abhinav/neurostack

3. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/Abhinav1234abhinav/neurostack

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/Abhinav1234abhinav/neurostack

5. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Abhinav1234abhinav/neurostack

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Abhinav1234abhinav/neurostack

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using neurostack with real data or production workflows.

• Capability evidence risk requires verification - GitHub / issue